> ## 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 Integration

> Connect external calendars to OpenIndex using ICS sources.

OpenIndex ingests external calendar data through ICS URLs. External calendar events are merged with your scheduled work items so you see everything in one place — no separate calendar app required.

<Note>
  Calendar integration is read-only. OpenIndex ingests events from ICS sources but does not write back to external calendar providers.
</Note>

***

## What you get

Once you add a calendar source, OpenIndex:

* Fetches and normalizes events from the ICS URL
* Merges external events with your scheduled work items in the `calendar day` and `calendar week` views
* Materializes availability blocks you can query via `GET /availability-blocks`
* Re-syncs automatically every 5 minutes

***

## Adding a calendar source

<Tabs>
  <Tab title="CLI (calendar command)">
    ```bash theme={null}
    oi calendar source create \
      --display-name "Personal" \
      --source-url "https://example.com/calendar.ics"
    ```
  </Tab>

  <Tab title="CLI (settings command)">
    ```bash theme={null}
    oi settings personal calendars create \
      --display-name "Personal" \
      --source-url "https://example.com/calendar.ics"
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /calendar-sources
    ```

    ```json theme={null}
    {
      "displayName": "Personal",
      "sourceUrl": "https://example.com/calendar.ics"
    }
    ```
  </Tab>
</Tabs>

Creating a source triggers an immediate sync attempt in addition to the regular 5-minute cadence.

***

## Listing calendar sources

```bash theme={null}
oi calendar source list
# or
oi settings personal calendars list
```

***

## Manually triggering a sync

If you want to pull the latest events without waiting for the next automatic sync:

```bash theme={null}
oi calendar source sync <source-id>
```

The API equivalent is `POST /calendar-sources/:id/sync`.

***

## Viewing the calendar

<CodeGroup>
  ```bash Daily view theme={null}
  oi calendar day --date 2026-03-01
  ```

  ```bash Weekly view theme={null}
  oi calendar week --start-date 2026-03-01
  ```

  ```bash Single event theme={null}
  oi calendar event <event-id>
  ```
</CodeGroup>

`calendar week` returns a 7-day window starting from `--start-date`. If you omit the date, it defaults to today.

`calendar event` returns full details for a single event ID from the day or week output. Pass `--include-raw-payload` to see the raw ICS data for that event.

***

## Viewing availability blocks

Availability blocks are derived from your calendar sources and scheduled work items. You can query them directly:

```bash theme={null}
GET /availability-blocks
```

***

## Sync cadence

| Trigger        | Behavior                               |
| -------------- | -------------------------------------- |
| Source created | Immediate sync attempt                 |
| Cron job       | Every 5 minutes for all active sources |
| Manual trigger | On demand via CLI or API               |

Each sync run writes a success or failure audit record so you can track sync health over time.

***

## Deleting a calendar source

```bash theme={null}
oi calendar source delete <source-id>
```

The API equivalent is `DELETE /calendar-sources/:id`. Deleting a source removes it from future sync runs. Previously ingested events are also removed.