Episodes API

Episodes are the core resource in Veronese. Use these endpoints to create, read, and update episodes programmatically.

Endpoints

Get episode

GET /episodes/:id.json

Returns the full episode state including transcript status.

Example response:

{
  "success": true,
  "episode": {
    "id": "abc123",
    "title": "My Recording",
    "canonical_state": "ready",
    "duration_seconds": 1840,
    "serie_id": "xyz789",
    "created_at": "2026-03-15T12:00:00Z",
    "transcript": {
      "status": "completed",
      "raw_text": "Hello, this is the transcript..."
    }
  }
}

Update episode

PATCH /episodes/:id.json

Update the episode title or content.

Request:

{
  "episode": {
    "title": "Updated Title"
  }
}

Create episode in a series

POST /series/:series_id/episodes.json

Create a new episode with a URL source.

Request:

{
  "episode": {
    "title": "My Episode",
    "source_url": "https://youtube.com/watch?v=..."
  },
  "idempotency_key": "unique-key-per-request"
}

The idempotency_key is optional. If provided, a duplicate request with the same key returns the existing episode instead of creating a new one.

Create episode (dashboard)

POST /dashboard/start_episode.json

Alternative endpoint for creating an episode without specifying a series upfront. Supports the same idempotency_key.

Get episode events

GET /episodes/:id/events.json

Returns the event log for an episode — useful for polling state changes.

Example response:

{
  "success": true,
  "events": [
    {
      "type": "state_change",
      "from": "ingesting",
      "to": "transcribing",
      "occurred_at": "2026-03-15T12:01:00Z"
    }
  ]
}

Canonical states

State	Meaning
draft	Episode created, no audio yet
ingesting	Audio is being downloaded/normalized
ready_for_transcription	Audio ready, waiting for transcription
transcribing	AI model is processing the audio
ready	Transcript complete and available
failed	An error occurred; see events for details

Polling for completion

Poll GET /episodes/:id.json until canonical_state is ready or failed. The CLI provides a veronese episode poll command that handles this automatically.