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

curl -X POST https://api.chronary.ai/v1/agents/agt_a1b2c3d4/ical-subscriptions \
  -H "Authorization: Bearer chr_sk_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"
  }'

Python

from chronary import Chronary

client = Chronary()

subscription = client.ical_subscriptions.create(
    agent_id="agt_a1b2c3d4",
    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

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

Python

for sub in client.ical_subscriptions.list(
    agent_id="agt_a1b2c3d4",
    status="active",
):
    print(f"{sub.label}: {sub.status}")

---

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

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

Python

client.ical_subscriptions.sync("isub_a1b2c3")

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 |