iCal Subscriptions

Import events from external calendars (Google Calendar, Outlook, etc.) into Chronary calendars. Imported events are read-only and block availability.

Create a subscription

POST /v1/agents/:agent_id/ical-subscriptions

Request body

Field	Type	Required	Description
calendar_id	string	Yes	Target calendar to import events into
url	string	Yes	HTTPS URL of the .ics feed
label	string	No	Human-readable label (1–255 characters)

Example

curl -X POST https://api.chronary.ai/v1/agents/agt_a1b2c3d4/ical-subscriptions \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "calendar_id": "cal_x1y2z3",
    "url": "https://calendar.google.com/calendar/ical/user%40gmail.com/basic.ics",
    "label": "Team Google Calendar"
  }'

Response 201 Created

{
  "id": "isub_a1b2c3",
  "agent_id": "agt_a1b2c3d4",
  "calendar_id": "cal_x1y2z3",
  "url": "https://calendar.google.com/calendar/ical/user%40gmail.com/basic.ics",
  "label": "Team Google Calendar",
  "status": "active",
  "last_synced_at": null,
  "created_at": "2026-04-04T12:00:00Z"
}

Errors

Status	Type	Cause
402	quota_exceeded	Subscription limit reached
404	not_found	Agent or calendar not found
422	validation_error	URL not HTTPS or invalid format

---

List subscriptions

GET /v1/agents/:agent_id/ical-subscriptions

Query parameters

Parameter	Type	Default	Description
status	string	—	Filter by active, error, or paused
limit	integer	50	1–200
offset	integer	0	Pagination offset

Example

curl "https://api.chronary.ai/v1/agents/agt_a1b2c3d4/ical-subscriptions?status=active" \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

---

Get a subscription

GET /v1/ical-subscriptions/:id

Errors

Status	Type	Cause
404	not_found	Subscription not found

---

Update a subscription

PATCH /v1/ical-subscriptions/:id

Request body

Field	Type	Description
label	string	1–255 characters
url	string	Must be HTTPS

At least one field must be provided.

Errors

Status	Type	Cause
404	not_found	Subscription not found
422	validation_error	Invalid URL format

---

Trigger manual sync

POST /v1/ical-subscriptions/:id/sync

Forces an immediate sync of the external feed. Returns 202 Accepted — the sync runs asynchronously.

Example

curl -X POST https://api.chronary.ai/v1/ical-subscriptions/isub_a1b2c3/sync \
  -H "Authorization: Bearer chr_sk_test_your_key_here"

Response 202 Accepted

{ "status": "syncing" }

Errors

Status	Type	Cause
404	not_found	Subscription not found

---

Delete a subscription

DELETE /v1/ical-subscriptions/:id

Returns 204 No Content. Previously imported events remain in the calendar.

Errors

Status	Type	Cause
404	not_found	Subscription not found