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`, `cancelled`, or `hold`
`metadata`	object	No	—	Key-value pairs, max 16KB JSON
`reminders`	integer[] \| null	No	inherit	Minutes before `start_time` to fire an `event.reminder` webhook (e.g. `[10, 1440]` = 10 min and 1 day before). Max 5 entries, each 1–40320 (28 days). `null` inherits the calendar’s `default_reminders`; `[]` means no reminders. See Reminders.
`hold_expires_at`	string	Conditional	—	Required when `status=hold`. ISO 8601 datetime 30s–15min in the future.
`hold_priority`	integer	No	`0`	Only valid with `status=hold`. 0–100. Higher-priority holds pre-empt lower.

curl -X POST https://api.chronary.ai/v1/calendars/cal_x1y2z3/events \
  -H "Authorization: Bearer chr_sk_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" }
  }'

from chronary import Chronary

client = Chronary()

event = client.events.create(
    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",
    metadata={"deal_id": "deal_789"},
)

Response `201 Created`

{
  "id": "evt_m1n2o3",
  "calendarId": "cal_x1y2z3",
  "orgId": "org_a1b2c3",
  "title": "Strategy sync with Acme Corp",
  "description": "Quarterly strategy alignment",
  "startTime": "2026-04-07T14:00:00Z",
  "endTime": "2026-04-07T14:30:00Z",
  "allDay": false,
  "status": "confirmed",
  "source": "internal",
  "metadata": { "deal_id": "deal_789" },
  "reminders": null,
  "holdExpiresAt": null,
  "holdPriority": 0,
  "deletedAt": null,
  "createdAt": "2026-04-04T12:00:00Z",
  "updatedAt": "2026-04-04T12:00:00Z"
}

reminders is null when the event inherits its calendar’s default_reminders.

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`, `cancelled`, or `hold`
`source`	string	—	`internal` or `external_ical`
`limit`	integer	50	1–200
`offset`	integer	0	Pagination offset

Example

curl
Python

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_your_key_here"

for event in client.events.list(
    calendar_id="cal_x1y2z3",
    start_after="2026-04-01T00:00:00Z",
    start_before="2026-04-30T23:59:59Z",
    status="confirmed",
):
    print(event.title)

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
Python

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

for event in client.agents.events.list(
    "agt_a1b2c3d4",
    start_after="2026-04-07T00:00:00Z",
):
    print(f"{event.title} ({event.calendar_id})")

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
`reminders`	integer[] \| null	Replaces the event’s reminders. `null` reverts to inheriting the calendar’s `default_reminders`; `[]` disables reminders. See Reminders.

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

Reminders

Reminders are timed notifications fired ahead of an event’s start_time. Each entry is an integer number of minutes before start — e.g. [10, 1440] fires 10 minutes and 1 day before. An array may hold up to 5 entries, each between 1 and 40320 (28 days).

Resolution

Reminders resolve in precedence order:

The event’s own reminders field, if set to an array.
The calendar’s default_reminders, if the event’s reminders is null.
The system default of [10] (10 minutes before) if neither is set.

A null value means “inherit from the level above”; an empty array [] means “explicitly no reminders” and stops resolution — it does not fall through to the default.

Delivery

Each resolved reminder fires an event.reminder webhook at start_time minus the offset. Reminders fire only for events with status: "confirmed" — tentative events, holds, and cancelled events do not fire reminders. Reminders are also emitted as VALARM components in the iCal feed so subscribed calendar apps display the alarm.

Temporal holds

Holds are tentative reservations that auto-release after a short TTL (max 15 minutes). Use them to eliminate race conditions when multiple agents compete for the same slot: place a hold first, decide second.

A hold behaves like a normal event for availability purposes — it blocks the slot against queries and other holds — but auto-expires if not confirmed.

Lifecycle

Create a hold — POST /v1/calendars/:cal_id/events with status: "hold" and hold_expires_at (30s–15min in the future). Fires event.hold_created.
Confirm — PUT /v1/events/:id/confirm promotes it to status: "confirmed". Fires event.hold_confirmed. event.started / event.ended lifecycle webhooks fire at the scheduled times.
Release — PUT /v1/events/:id/release manually releases the hold. Fires event.hold_released.
Auto-expire — if not confirmed or released by hold_expires_at, the hold is cancelled and event.hold_expired fires.

Priority bumping

When creating a hold that overlaps an existing hold on the same calendar:

Higher priority wins. If the new hold’s hold_priority is strictly greater than the existing one’s, the existing hold is cancelled (event.hold_expired fires) and the new hold is created.
Equal or lower priority → 409 conflict. The new hold is rejected with error hold_conflict.

A single create request with priority bumping therefore fires two webhooks in order: event.hold_expired (for the bumped hold), then event.hold_created (for the new one).

Confirm a hold

PUT /v1/events/:id/confirm

curl
Python

curl -X PUT https://api.chronary.ai/v1/events/evt_m1n2o3/confirm \
  -H "Authorization: Bearer chr_sk_your_key_here"

event = client.events.confirm("evt_m1n2o3")

Returns the confirmed event (200 OK). Fires event.hold_confirmed.

Errors

Status	Type	Cause
`403`	`forbidden`	External iCal events cannot be confirmed
`404`	`not_found`	Event not found
`409`	`conflict`	Event is not a hold (`not_a_hold`), or the hold has already expired (`hold_expired`)

Release a hold

PUT /v1/events/:id/release

curl
Python

curl -X PUT https://api.chronary.ai/v1/events/evt_m1n2o3/release \
  -H "Authorization: Bearer chr_sk_your_key_here"

event = client.events.release("evt_m1n2o3")

Returns the released (now cancelled) event (200 OK). Fires event.hold_released.

Errors

Status	Type	Cause
`403`	`forbidden`	External iCal events cannot be released
`404`	`not_found`	Event not found
`409`	`conflict`	Event is not a hold

Constraints

PATCH on a hold is rejected with 400 invalid_transition — use /confirm, /release, or wait for TTL.
PATCH cannot set status=hold on a non-hold event.
hold_expires_at is write-once at create time.
Holds count against your events quota (same as regular event creation).

Events

Create an event

Request body

Example

Response 201 Created

Errors

List events

Query parameters

Example

Response 200 OK

Errors

List events by agent

Example

Get an event

Errors

Update an event

Request body

Errors

Delete an event

Errors

Reminders

Resolution

Delivery

Temporal holds

Lifecycle

Priority bumping

Confirm a hold

Errors

Release a hold

Errors

Constraints

Response `201 Created`

Response `200 OK`