Calendars

Calendars contain events and generate iCal feed URLs. They can be org-level (shared) or owned by a specific agent.

Create a calendar

Create an org-level calendar or an agent-owned calendar:

POST /v1/calendars
POST /v1/agents/:agent_id/calendars

Request body

Field	Type	Required	Default	Description
`name`	string	Yes	—	1–255 characters
`timezone`	string	Yes	—	IANA timezone (e.g., `America/New_York`)
`agent_status`	string	No	`idle`	`idle`, `working`, `waiting`, or `error`. See Agent status.
`default_reminders`	integer[] \| null	No	—	Minutes before `start_time` that events in this calendar inherit when they don’t set their own `reminders`. Max 5 entries, each 1–40320 (28 days). See Reminder defaults.
`metadata`	object	No	—	Key-value pairs, max 16KB JSON

curl -X POST https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Meetings",
    "timezone": "America/New_York",
    "agent_status": "idle"
  }'

from chronary import Chronary

client = Chronary()

# Agent-owned calendar
calendar = client.agents.calendars.create(
    "agt_a1b2c3d4",
    name="Sales Meetings",
    timezone="America/New_York",
    agent_status="idle",
)

# Org-level calendar
calendar = client.calendars.create(
    name="Sales Meetings",
    timezone="America/New_York",
)

Response `201 Created`

{
  "id": "cal_01H9X4M2P5R8T6V0",
  "orgId": "org_01H9X4M2P5R8T6V0",
  "agentId": "agt_01H9X4M2P5R8T6V0",
  "name": "Sales Meetings",
  "timezone": "America/New_York",
  "metadata": {},
  "externalId": null,
  "provider": null,
  "deletedAt": null,
  "createdAt": "2026-04-04T12:00:00Z",
  "updatedAt": "2026-04-04T12:00:00Z",
  "agent_status": "idle",
  "default_reminders": null,
  "ical_url": "https://api.chronary.ai/ical/abc123def456.ics"
}

Errors

Status	Type	Cause
`429`	`quota_exceeded`	Calendar limit reached on your plan

List calendars

GET /v1/calendars
GET /v1/agents/:agent_id/calendars

Query parameters

Parameter	Type	Default	Description
`include`	string	—	Set to `all` to include agent-owned calendars (org-level endpoint only)
`limit`	integer	50	1–200
`offset`	integer	0	Pagination offset

Example

curl
Python

# List all org calendars including agent-owned
curl "https://api.chronary.ai/v1/calendars?include=all" \
  -H "Authorization: Bearer chr_sk_your_key_here"

# List calendars for a specific agent
curl "https://api.chronary.ai/v1/agents/agt_a1b2c3d4/calendars" \
  -H "Authorization: Bearer chr_sk_your_key_here"

# All calendars including agent-owned
for cal in client.calendars.list(include="all"):
    print(cal.name)

# Agent-owned calendars
for cal in client.agents.calendars.list("agt_a1b2c3d4"):
    print(cal.name)

Response `200 OK`

{
  "data": [
    {
      "id": "cal_x1y2z3",
      "name": "Sales Meetings",
      "timezone": "America/New_York",
      "ical_url": "https://api.chronary.ai/ical/abc123def456.ics",
      ...
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

Get a calendar

GET /v1/calendars/:id

Example

curl
Python

curl https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_your_key_here"

calendar = client.calendars.get("cal_x1y2z3")

Errors

Status	Type	Cause
`404`	`not_found`	Calendar not found

Get temporal context

GET /v1/calendars/:id/context

Returns a “what’s happening now” snapshot for a calendar: the currently active event, the next upcoming event, recently ended events, and everything starting in the next 24 hours. Designed for agents that want a single cheap call to orient themselves before planning or responding.

Use cases

An agent starting a turn reads context to decide whether it’s free, in a meeting, or about to start one.
A status dashboard or MCP client surfaces a compact “right now” summary without paginating events.
A planner looks at upcoming (next 24h) to decide whether to schedule new work immediately or defer it.

Example

curl
TypeScript

curl https://api.chronary.ai/v1/calendars/cal_01H9X4M2P5R8T6V0/context \
  -H "Authorization: Bearer chr_sk_your_key_here"

import { Chronary } from '@chronary/sdk';

const client = new Chronary({ apiKey: process.env.CHRONARY_API_KEY! });

const context = await client.calendars.getContext('cal_01H9X4M2P5R8T6V0');
if (context.current_event) {
  console.log(`Busy until ${context.current_event.endTime}`);
} else if (context.next_event) {
  console.log(`Next: ${context.next_event.title} at ${context.next_event.startTime}`);
}

Response `200 OK`

Field	Type	Description
`calendar_id`	string	The calendar this snapshot is for
`now`	string (datetime)	Server-side timestamp the snapshot was computed at
`agent_status`	string	The calendar’s current `agent_status` (see below)
`current_event`	object \| null	The event whose window contains `now`, or `null` if none
`next_event`	object \| null	The next event starting strictly after `now`, or `null`
`recent_events`	array	Up to 3 most recently ended events, newest first
`upcoming`	array	Up to 5 events starting within the next 24 hours, earliest first

Cancelled and soft-deleted events are excluded from all four event lists.

{
  "calendar_id": "cal_01H9X4M2P5R8T6V0",
  "now": "2026-04-16T14:05:00.000Z",
  "agent_status": "working",
  "current_event": {
    "id": "evt_01H9X4M2P5R8T6V0",
    "calendarId": "cal_01H9X4M2P5R8T6V0",
    "title": "Strategy sync with Acme Corp",
    "startTime": "2026-04-16T14:00:00.000Z",
    "endTime": "2026-04-16T14:30:00.000Z",
    "status": "confirmed",
    "source": "internal",
    "metadata": {},
    "createdAt": "2026-04-10T12:00:00.000Z",
    "updatedAt": "2026-04-10T12:00:00.000Z"
  },
  "next_event": { "...": "..." },
  "recent_events": [ { "...": "..." } ],
  "upcoming": [ { "...": "..." } ]
}

Errors

Status	Type	Cause
`404`	`not_found`	Calendar not found

Update a calendar

PATCH /v1/calendars/:id

Request body

Field	Type	Description
`name`	string	1–255 characters
`timezone`	string	IANA timezone identifier
`agent_status`	string	`idle`, `working`, `waiting`, or `error`. See Agent status.
`default_reminders`	integer[] \| null	Replaces the calendar’s reminder defaults. Set to `null` to clear. See Reminder defaults.
`metadata`	object	Replaces existing metadata

At least one field must be provided.

Example

curl
Python

curl -X PATCH https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sales Meetings (Q2)" }'

updated = client.calendars.update("cal_x1y2z3", name="Sales Meetings (Q2)")

Errors

Status	Type	Cause
`404`	`not_found`	Calendar not found

Delete a calendar

DELETE /v1/calendars/:id

Returns 204 No Content. Deleting a calendar removes all its events.

Example

curl
Python

curl -X DELETE https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_your_key_here"

client.calendars.delete("cal_x1y2z3")

Errors

Status	Type	Cause
`404`	`not_found`	Calendar not found

Agent status

Every calendar carries an agent_status field that lets an agent advertise its current operational state to anyone reading the calendar (other agents, dashboards, humans subscribed to the iCal feed). It defaults to idle on create and can be changed at any time via PATCH /v1/calendars/:id. It is also surfaced on GET /v1/calendars/:id/context so callers can read state and upcoming work in one request.

Value	Meaning
`idle`	The agent is running but has no active work. Available to take on new tasks.
`working`	The agent is actively processing a task — e.g. running a tool, making API calls, or writing to a calendar.
`waiting`	The agent is blocked on external input — awaiting a human reply, a webhook, or a dependent job.
`error`	The agent has hit an unrecoverable failure and is not making progress. Operators should intervene.

The field is free-form on the server — no transitions are enforced — so agents pick whichever value best describes their state. See the Advertising agent state pattern for a full example.

Reminder defaults

default_reminders is an array of integers — minutes before an event’s start_time — that every event in the calendar inherits when it doesn’t set its own reminders. For example, [10, 1440] reminds 10 minutes and 1 day before. Up to 5 entries, each 1–40320 (28 days).

Resolution for any given event is: the event’s own reminders → the calendar’s default_reminders → the system default of [10]. A null value at either level means “inherit”; an empty array [] means “explicitly no reminders”. See Reminders on events for the full precedence rules and delivery behavior.

Calendars

Create a calendar

Request body

Example

Response 201 Created

Errors

List calendars

Query parameters

Example

Response 200 OK

Get a calendar

Example

Errors

Get temporal context

Use cases

Example

Response 200 OK

Errors

Update a calendar

Request body

Example

Errors

Delete a calendar

Example

Errors

Agent status

Reminder defaults

Response `201 Created`

Response `200 OK`

Response `200 OK`