# Docs · REST API reference

> Markdown mirror of https://onairflow.com/docs/api · last updated
> August 22, 2026

The API covers the rundown surface: shows, stories, columns, attachments, and
story types. It is the same surface the MCP server and agent skill use under
the hood. Anything outside this surface returns `403`.

## Authentication

Send your agent's key as a bearer token on every request:

```
Authorization: Bearer oaf_xxxxxxxxxxxx
```

Keys are minted per agent in **Settings → AI → Agents & keys** with the
scopes you choose (`rundown:read`, `rundown:write`), and can be revoked there
at any time.

## Base URL

All endpoints are served from `https://api.onairflow.com`.

## MCP

The same surface is available over the Model Context Protocol (Streamable
HTTP) at `https://api.onairflow.com/mcp`. Two ways to connect:

**Hosted MCP connector (Claude, ChatGPT, Grok).** Add
`https://api.onairflow.com/mcp` as a custom connector. The client discovers
OnAirFlow's OAuth endpoints, registers itself, and sends you to a consent
screen where any team member approves the connection and its scopes (read-only is
an option). Each connection becomes its own named agent in your org; view or
revoke it any time under Settings → AI → Assistants. Tokens rotate
automatically — nothing to paste or renew.

**Bearer key (Claude Code, Cursor, fleets).** Any MCP client that supports
custom headers can use an `oaf_` key directly:

```bash
claude mcp add --transport http onairflow https://api.onairflow.com/mcp --header "Authorization: Bearer oaf_xxxxxxxxxxxx"
```

The MCP server exposes eleven rundown tools: shows, stories, columns, and
attachments — including `upload_attachment`, which takes base64 content up to
15MB decoded and requires the org to have Google Drive storage connected
(agent uploads land in your own Drive, never in OnAirFlow's metered storage).
Larger files go over REST: `POST /api/uploads/:storyId` (multipart, ≤50MB).
Supported upload types: images (jpeg/png/gif/webp), PDF, audio (mp3/wav),
video (mp4/mov), text (plain/markdown/csv/json), and Word documents.

## Endpoints

| Method | Path | Description | Scope |
|--------|------|-------------|-------|
| GET | `/api/shows` | List shows. Optional `?status=draft\|live\|completed` | rundown:read |
| GET | `/api/shows/:showId` | Get a show's full rundown — stories and columns | rundown:read |
| POST | `/api/shows/:showId/stories` | Create a story in a column (body: columnId, title, …) | rundown:write |
| PUT | `/api/shows/:showId/stories/:storyId` | Update story fields | rundown:write |
| PUT | `/api/shows/:showId/stories/:storyId/move` | Move a story (body: targetColumnId, newPosition — zero-based) | rundown:write |
| DELETE | `/api/shows/:showId/stories/:storyId` | Delete a story | rundown:write |
| POST | `/api/shows/:showId/columns` | Create a column (appended at the end) | rundown:write |
| PUT | `/api/shows/:showId/columns/:columnId` | Rename a column | rundown:write |
| DELETE | `/api/shows/:showId/columns/:columnId` | Delete a column | rundown:write |
| POST | `/api/uploads/:storyId` | Attach a file to a story (multipart "file", ≤50MB) | rundown:write |
| DELETE | `/api/uploads/:attachmentId` | Delete a story attachment | rundown:write |
| GET | `/api/story-types` | List your org's story types | rundown:read |

## Errors

- `401` — missing, invalid, revoked, or expired key.
- `403` — route outside the agent surface, or the key lacks the required
  scope.
- `404` — the resource doesn't exist in your organization.
- `409` — story edit conflict: another writer changed the same field since
  you read it. Re-read and retry.
- `429` — rate limited. Back off and retry with the `Retry-After` header.

## Notes

- Story and column writes use the `PUT` verb.
- `newPosition` on move is a zero-based index within the target column.
- New columns are always appended; there is no position parameter on create.
- AI note generation is retired and is not available to API keys — requests to
  it return `403`. To use AI on a rundown, connect your own assistant over MCP —
  see https://onairflow.com/docs/guide/ai-host-notes.md