Calendar API

OpenIndex ingests external calendars via ICS (iCalendar) URLs. Calendar sources sync on a regular schedule and materialize availability blocks that agents and users can query when scheduling work. All calendar endpoints require a Bearer token. See API Authentication.

Calendar ingest is read-only. OpenIndex does not write back to external calendar providers.

Calendar sources

List sources

GET /calendar-sources
Authorization: Bearer <your-pat>

Returns all calendar sources accessible to the authenticated user.

Create a source

POST /calendar-sources
Authorization: Bearer <your-pat>
Content-Type: application/json

string

required

Human-readable name for this calendar source (e.g. Team Availability, On-call Schedule).

string

required

The ICS feed URL. Must be publicly accessible or accessible with credentials embedded in the URL.

curl --request POST \
  --url https://your-deployment.convex.site/calendar-sources \
  --header 'Authorization: Bearer oi_pat_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Team On-call",
    "sourceUrl": "https://calendar.example.com/oncall.ics"
  }'

{
  "id": "cs_abc123",
  "displayName": "Team On-call",
  "sourceUrl": "https://calendar.example.com/oncall.ics",
  "lastSyncedAt": null,
  "createdAt": "2026-03-31T10:00:00Z"
}

Creating a source triggers an immediate sync attempt. The source is usable as soon as the first sync completes.

Delete a source

DELETE /calendar-sources/:id
Authorization: Bearer <your-pat>

Removes the source and all associated events and availability blocks.

Trigger a manual sync

POST /calendar-sources/:id/sync
Authorization: Bearer <your-pat>

Triggers an immediate sync for the source, regardless of the automatic sync schedule. Sync results are written to the audit log.

Sync cadence

OpenIndex syncs calendar sources automatically every 5 minutes via a scheduled cron job. The base and maximum sync intervals are configurable via environment variables:

Variable	Default	Description
`CALENDAR_SYNC_BASE_INTERVAL_MS`	`1800000` (30 min)	Base sync backoff interval.
`CALENDAR_SYNC_MAX_INTERVAL_MS`	`172800000` (48 hrs)	Maximum time between syncs.

See Environment Variables for details.

Calendar events

List events

GET /calendar-events
Authorization: Bearer <your-pat>

string

Filter events by date (ISO 8601 format, e.g. 2026-04-15). Returns events occurring on or spanning this date.

string

Filter events associated with a specific domain.

Get a single event

GET /calendar-events/:id
Authorization: Bearer <your-pat>

Returns the full event record including summary, start/end times, location, and source metadata.

Availability blocks

GET /availability-blocks
Authorization: Bearer <your-pat>

Returns materialized availability blocks derived from calendar events. Agents use availability blocks when scheduling work items to avoid conflicts with existing calendar commitments.

Overview

Work Items

Integrations

Calendar sources

List sources

Create a source

Delete a source

Trigger a manual sync

Sync cadence

Calendar events

List events

Get a single event

Availability blocks

​Calendar sources

​List sources

​Create a source

​Delete a source

​Trigger a manual sync

​Sync cadence

​Calendar events

​List events

​Get a single event

​Availability blocks

Calendar sources

List sources

Create a source

Delete a source

Trigger a manual sync

Sync cadence

Calendar events

List events

Get a single event

Availability blocks