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",
  "agent_id": "agt_01H9X4M2P5R8T6V0",
  "name": "Sales Meetings",
  "timezone": "America/New_York",
  "agent_status": "idle",
  "default_reminders": null,
  "metadata": {},
  "ical_url": "https://api.chronary.ai/ical/abc123def456.ics",
  "created_at": "2026-04-04T12:00:00Z",
  "updated_at": "2026-04-04T12:00:00Z"
}

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.end_time}`);
} else if (context.next_event) {
  console.log(`Next: ${context.next_event.title} at ${context.next_event.start_time}`);
}

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",
    "calendar_id": "cal_01H9X4M2P5R8T6V0",
    "title": "Strategy sync with Acme Corp",
    "start_time": "2026-04-16T14:00:00.000Z",
    "end_time": "2026-04-16T14:30:00.000Z",
    "status": "confirmed",
    "source": "internal",
    "metadata": {},
    "created_at": "2026-04-10T12:00:00.000Z",
    "updated_at": "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`