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	Description
name	string	Yes	1–255 characters
timezone	string	Yes	IANA timezone (e.g., America/New_York)
metadata	object	No	Key-value pairs, max 16KB JSON

Example

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

Response 201 Created

{
  "id": "cal_x1y2z3",
  "org_id": "org_abc",
  "agent_id": "agt_a1b2c3d4",
  "name": "Sales Meetings",
  "timezone": "America/New_York",
  "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

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

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

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 https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

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
metadata	object	Replaces existing metadata

At least one field must be provided.

Example

curl -X PATCH https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "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 -X DELETE https://api.chronary.ai/v1/calendars/cal_x1y2z3 \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

Errors

Status	Type	Cause
404	not_found	Calendar not found