Skip to main content
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
​
body.displayName
string
required
Human-readable name for this calendar source (e.g. Team Availability, On-call Schedule).
​
body.sourceUrl
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"
  }'
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:
VariableDefaultDescription
CALENDAR_SYNC_BASE_INTERVAL_MS1800000 (30 min)Base sync backoff interval.
CALENDAR_SYNC_MAX_INTERVAL_MS172800000 (48 hrs)Maximum time between syncs.
See Environment Variables for details.

​
Calendar events

​
List events

GET /calendar-events
Authorization: Bearer <your-pat>
​
query.date
string
Filter events by date (ISO 8601 format, e.g. 2026-04-15). Returns events occurring on or spanning this date.
​
query.domainId
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.