> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar API

> Manage ICS calendar sources and query events via the OpenIndex 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](/api/authentication).

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

## Calendar sources

### List sources

```bash theme={null}
GET /calendar-sources
Authorization: Bearer <your-pat>
```

Returns all calendar sources accessible to the authenticated user.

### Create a source

```bash theme={null}
POST /calendar-sources
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.displayName" type="string" required>
  Human-readable name for this calendar source (e.g. `Team Availability`, `On-call Schedule`).
</ParamField>

<ParamField path="body.sourceUrl" type="string" required>
  The ICS feed URL. Must be publicly accessible or accessible with credentials embedded in the URL.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "cs_abc123",
    "displayName": "Team On-call",
    "sourceUrl": "https://calendar.example.com/oncall.ics",
    "lastSyncedAt": null,
    "createdAt": "2026-03-31T10:00:00Z"
  }
  ```
</CodeGroup>

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

### Delete a source

```bash theme={null}
DELETE /calendar-sources/:id
Authorization: Bearer <your-pat>
```

Removes the source and all associated events and availability blocks.

### Trigger a manual sync

```bash theme={null}
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](/configuration/environment) for details.

## Calendar events

### List events

```bash theme={null}
GET /calendar-events
Authorization: Bearer <your-pat>
```

<ParamField path="query.date" type="string">
  Filter events by date (ISO 8601 format, e.g. `2026-04-15`). Returns events occurring on or spanning this date.
</ParamField>

<ParamField path="query.domainId" type="string">
  Filter events associated with a specific domain.
</ParamField>

### Get a single event

```bash theme={null}
GET /calendar-events/:id
Authorization: Bearer <your-pat>
```

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

## Availability blocks

```bash theme={null}
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.