Events

Events are time-bound entries within a calendar. They support statuses, metadata, and trigger webhooks on changes.

Create an event

POST /v1/calendars/:cal_id/events

Request body

Field	Type	Required	Default	Description
title	string	Yes	—	1–500 characters
start_time	string	Yes	—	ISO 8601 datetime (UTC)
end_time	string	Yes	—	ISO 8601 datetime (must be after start_time)
description	string	No	—	Free-text description
all_day	boolean	No	false	Mark as all-day event
status	string	No	confirmed	confirmed, tentative, or cancelled
metadata	object	No	—	Key-value pairs, max 16KB JSON

Example

curl -X POST https://api.chronary.ai/v1/calendars/cal_x1y2z3/events \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Strategy sync with Acme Corp",
    "start_time": "2026-04-07T14:00:00Z",
    "end_time": "2026-04-07T14:30:00Z",
    "description": "Quarterly strategy alignment",
    "metadata": { "deal_id": "deal_789" }
  }'

Response 201 Created

{
  "id": "evt_m1n2o3",
  "calendar_id": "cal_x1y2z3",
  "title": "Strategy sync with Acme Corp",
  "start_time": "2026-04-07T14:00:00Z",
  "end_time": "2026-04-07T14:30:00Z",
  "description": "Quarterly strategy alignment",
  "all_day": false,
  "status": "confirmed",
  "source": "internal",
  "metadata": { "deal_id": "deal_789" },
  "created_at": "2026-04-04T12:00:00Z",
  "updated_at": "2026-04-04T12:00:00Z"
}

Triggers an event.created webhook.

Errors

Status	Type	Cause
404	not_found	Calendar not found

---

List events

GET /v1/calendars/:cal_id/events

Query parameters

Parameter	Type	Default	Description
start_after	datetime	—	Events starting after this time
start_before	datetime	—	Events starting before this time
status	string	—	confirmed, tentative, or cancelled
source	string	—	internal or external_ical
limit	integer	50	1–200
offset	integer	0	Pagination offset

Example

curl "https://api.chronary.ai/v1/calendars/cal_x1y2z3/events?start_after=2026-04-01T00:00:00Z&start_before=2026-04-30T23:59:59Z&status=confirmed" \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

Response 200 OK

{
  "data": [ ... ],
  "total": 15,
  "limit": 50,
  "offset": 0
}

Errors

Status	Type	Cause
404	not_found	Calendar not found

---

List events by agent

Returns events across all calendars owned by an agent.

GET /v1/agents/:agent_id/events

Same query parameters as calendar-scoped listing.

Example

curl "https://api.chronary.ai/v1/agents/agt_a1b2c3d4/events?start_after=2026-04-07T00:00:00Z" \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

---

Get an event

GET /v1/calendars/:cal_id/events/:id

Errors

Status	Type	Cause
404	not_found	Event not found

---

Update an event

PATCH /v1/calendars/:cal_id/events/:id

Request body

Field	Type	Description
title	string	1–500 characters
description	string | null	Set to null to clear
start_time	datetime	ISO 8601
end_time	datetime	ISO 8601
all_day	boolean	—
status	string	confirmed, tentative, or cancelled
metadata	object	Replaces existing metadata

At least one field must be provided. Triggers an event.updated webhook.

Errors

Status	Type	Cause
403	forbidden	External iCal events are read-only
404	not_found	Event or calendar not found

---

Delete an event

DELETE /v1/calendars/:cal_id/events/:id

Returns 204 No Content. Triggers an event.deleted webhook.

Errors

Status	Type	Cause
403	forbidden	External iCal events are read-only
404	not_found	Event or calendar not found