iCal Subscriptions

iCal subscriptions let you import events from external calendars (Google Calendar, Outlook, etc.) into Chronary. This means your agents’ availability queries can account for events from human calendars — preventing double-bookings.

How it works

1. You provide a public or authenticated .ics feed URL from an external calendar
2. Chronary periodically syncs events from that feed into a target calendar
3. Imported events appear alongside native events and block availability
4. Imported events are read-only — they can’t be edited or deleted via the API

Create a subscription

curl

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": "Alex'\''s Google Calendar"
  }'

JavaScript

const response = await fetch(
  'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/ical-subscriptions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer chr_sk_test_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      calendar_id: 'cal_x1y2z3',
      url: 'https://calendar.google.com/calendar/ical/user%40gmail.com/basic.ics',
      label: "Alex's Google Calendar",
    }),
  }
);
const subscription = await response.json();
console.log(subscription.id); // "isub_a1b2c3"

Python

response = requests.post(
    'https://api.chronary.ai/v1/agents/agt_a1b2c3d4/ical-subscriptions',
    headers={'Authorization': 'Bearer chr_sk_test_your_key_here'},
    json={
        'calendar_id': 'cal_x1y2z3',
        'url': 'https://calendar.google.com/calendar/ical/user%40gmail.com/basic.ics',
        'label': "Alex's Google Calendar",
    },
)
subscription = response.json()

Fields

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)

Caution

The subscription URL must use HTTPS. HTTP URLs are rejected for security.

List subscriptions

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

Filter by status: active, error, or paused.

Get a subscription

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

Update a subscription

Change the label or URL:

curl -X PATCH https://api.chronary.ai/v1/ical-subscriptions/isub_a1b2c3 \
  -H "Authorization: Bearer chr_sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Alex'\''s Work Calendar" }'

Trigger a manual sync

Force an immediate sync instead of waiting for the next scheduled cycle:

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

Returns 202 Accepted — the sync runs asynchronously.

Delete a subscription

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

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

Subscription statuses

Status	Meaning
active	Syncing normally
error	Last sync failed (URL unreachable, invalid iCal, etc.)
paused	Manually paused

Getting external calendar URLs

Google Calendar: Settings > Calendar > “Secret address in iCal format”

Outlook/Office 365: Calendar settings > Shared calendars > Publish a calendar > ICS link

Apple iCloud: Calendar sharing > Public Calendar > copy the URL

Imported events

Events imported via iCal subscriptions:

• Have source: "external_ical" in the event data
• Are read-only — update/delete returns 403 Forbidden
• Block availability just like native events
• Are updated on each sync cycle (changed events are updated, deleted events are removed)