API Reference

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created in Settings → Developer → API Keys.

Keys are prefixed with pr_ and are only shown once at creation. They are stored as SHA-256 hashes — preroll.io never stores your raw key.

curl -H "Authorization: Bearer pr_your_api_key_here" \
  https://api.preroll.io/api/v1/dashboard

Response Format

All endpoints return a consistent JSON envelope.

Success

{
  "data": { ... }
}

Error

{
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE"
  }
}

HTTP status codes follow standard conventions: 200 for success, 400 for bad requests, 401 for unauthorized, 403 for forbidden, 404 for not found, and 500 for server errors.

Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/dashboard`	Dashboard summary (stats, attention list, recent activity)
`GET`	`/api/v1/clients`	List all clients in your organization
`POST`	`/api/v1/clients`	Create a new client
`GET`	`/api/v1/clients/{client_id}`	Get client details
`PATCH`	`/api/v1/clients/{client_id}`	Update a client
`GET`	`/api/v1/shows`	List all shows (optionally filter by `?client_id=`)
`POST`	`/api/v1/clients/{client_id}/shows`	Create a new show
`GET`	`/api/v1/episodes`	List episodes (filter with `?show_id=`, `?status=`, `?stage_id=`)
`POST`	`/api/v1/shows/{show_id}/episodes`	Create a new episode for a show
`PATCH`	`/api/v1/shows/{show_id}/episodes/{episode_id}`	Update an episode
`GET`	`/api/v1/deliverables`	List deliverables (filter with `?episode_id=`, `?status=`)
`POST`	`/api/v1/episodes/{episode_id}/deliverables`	Create a deliverable
`PATCH`	`/api/v1/deliverables/{deliverable_id}`	Update a deliverable
`POST`	`/api/v1/episodes/{episode_id}/transcribe`	Start audio transcription (Deepgram)
`POST`	`/api/v1/episodes/{episode_id}/generate`	Generate AI content from transcript
`POST`	`/api/v1/episodes/{episode_id}/pipeline`	Run full AI pipeline (transcribe + generate)
`POST`	`/api/v1/ai/chat`	Stream AI chat response (SSE)
`GET`	`/api/v1/storage`	Storage usage summary and file list
`DELETE`	`/api/v1/storage/files/{file_id}`	Delete a stored file
`GET`	`/api/v1/tags`	List all tags
`POST`	`/api/v1/tags`	Create a tag
`GET`	`/api/v1/webhook-endpoints`	List webhook endpoints
`POST`	`/api/v1/webhook-endpoints`	Create a webhook endpoint

Query Parameters

`GET /api/v1/episodes`

Parameter	Type	Description
`show_id`	`uuid`	Filter episodes by show
`status`	`string`	Filter by status (`draft`, `in_progress`, `published`)
`stage_id`	`uuid`	Filter by pipeline stage

`GET /api/v1/deliverables`

Parameter	Type	Description
`episode_id`	`uuid`	Filter deliverables by episode
`status`	`string`	Filter by status (`pending`, `approved`, `revision_requested`)

Creating an Episode

curl -X POST \
  -H "Authorization: Bearer pr_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode 42: The Answer",
    "description": "In this episode we discuss...",
    "episode_number": 42
  }' \
  https://api.preroll.io/api/v1/shows/{show_id}/episodes

Updating an Episode

curl -X PATCH \
  -H "Authorization: Bearer pr_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode 42: The Updated Title",
    "status": "in_progress"
  }' \
  https://api.preroll.io/api/v1/shows/{show_id}/episodes/{episode_id}

Rate Limits

There are no enforced rate limits at this time. Please be respectful with your request volume. Rate limiting may be introduced in the future with standard 429 responses and Retry-After headers.

On this page