EPISODIC Agentic podcast production

Maturity Active development 33 of 120 roadmap tasks complete (1 of 6 phases). Not a released product.

API reference

The REST surface Episodic actually serves

21 routes, read from the application's route table rather than transcribed. Anything not listed here is not registered.

How this list is produced

Because a hand-maintained endpoint list is a hand-maintained lie.

Paths and methods on this page are extracted from the Falcon composition root in the Episodic repository and checked against this site at build time. A route that gains a method changes this page; a route documented here that stops existing fails the build.

Purpose text is written by hand and validated against the same route table, so a description cannot outlive the endpoint it describes.

Falcon composition root

Before the first request

6 behaviours apply across the surface. One of them is a gap worth knowing about.

Authorization

In progress

Authorization middleware runs ahead of every resource except health routes, which bypass authentication. It supplies the authenticated principal; tenancy isolation is roadmap phase 5.

Idempotency

Available

Side-effecting POST requests to the intake surface require an Idempotency-Key. The key is scoped to the authenticated principal. A repeat with the same canonical body replays the stored response; the same key with a different body returns 409 Conflict.

Optimistic locking

Available

Profile and template updates carry expected_revision. A stale revision is refused rather than overwriting a concurrent edit.

Errors

Available

A single error serializer produces a consistent error body across every resource.

Pagination, filtering, and role enforcement

Available

Pagination, filtering, and role enforcement are delivered by the request surfaces that expose them.

Rate limits

Planned

No rate-limit contract is defined yet; do not assume one.

Endpoint groups

21 registered routes across 6 groups.

Health and readiness 2 routes

Methods Path Purpose
GET /health/live Reports that the process has booted. Used as the container liveness probe.
GET /health/ready Reports infrastructure readiness, including database connectivity. Returns 503 when the check fails so the platform withholds traffic.

Reference documents and revisions 4 routes

Methods Path Purpose
GET /v1/reference-document-revisions/{revision_id} Read a pinned reference-document revision by identifier.
GETPOST /v1/series-profiles/{profile_id}/reference-documents List reusable reference documents for a series, or create one. Host and guest profiles are series-aligned reference documents.
GETPATCH /v1/series-profiles/{profile_id}/reference-documents/{document_id} Read or update a single reference document.
GETPOST /v1/series-profiles/{profile_id}/reference-documents/{document_id}/revisions List revisions of a reference document, or add one.

Reference bindings 2 routes

Methods Path Purpose
GETPOST /v1/reference-bindings List reference bindings, or bind a pinned revision to a series, template, or episode scope.
GET /v1/reference-bindings/{binding_id} Read a single reference binding, including its effective_from_episode_id scope.

Episode templates 3 routes

Methods Path Purpose
GETPOST /v1/episode-templates List episode templates, or create one linked to a series profile.
GETPATCH /v1/episode-templates/{template_id} Read an episode template, or update it under optimistic locking.
GET /v1/episode-templates/{template_id}/history Retrieve the change history for an episode template.

Series profiles 5 routes

Methods Path Purpose
GETPOST /v1/series-profiles List series profiles, or create one carrying tone descriptors, segment ordering, audio preferences, and guardrails.
GETPATCH /v1/series-profiles/{profile_id} Read a series profile, or update it under optimistic locking with expected_revision.
GET /v1/series-profiles/{profile_id}/brief Fetch the structured brief payload that downstream generators consume.
GET /v1/series-profiles/{profile_id}/history Retrieve the change history for a series profile.
GET /v1/series-profiles/{profile_id}/resolved-bindings Resolve the exact reference-document revisions that apply to a target episode.

Source intake 5 routes

Methods Path Purpose
GETPOST /v1/ingestion-jobs List ingestion jobs, or create one. Requires an Idempotency-Key.
GET /v1/ingestion-jobs/{job_id} Poll an ingestion job until its source context is ready for draft generation.
GETPOST /v1/ingestion-jobs/{job_id}/sources List the sources attached to an ingestion job, or attach an upload or remote source URI.
POST /v1/uploads Upload one source document. Requires an Idempotency-Key.
GET /v1/uploads/{upload_id} Read the stored metadata for an uploaded source document.

A worked intake sequence

The narrowest useful path through the implemented surface. Placeholders are obvious on purpose.

Upload a source, attach it to a job, and poll until ready Request shapes follow the users' guide; field names are not a published schema 
curl -X POST "$EPISODIC_BASE/v1/uploads" \
  -H "Authorization: Bearer REPLACE_WITH_TOKEN" \
  -H "Idempotency-Key: 2f8c1e40-upload-01" \
  -F "[email protected]"

curl -X POST "$EPISODIC_BASE/v1/ingestion-jobs" \
  -H "Authorization: Bearer REPLACE_WITH_TOKEN" \
  -H "Idempotency-Key: 2f8c1e40-job-01" \
  -H "Content-Type: application/json" \
  -d '{"series_profile_id": "REPLACE_WITH_PROFILE_ID"}'

curl -X POST "$EPISODIC_BASE/v1/ingestion-jobs/$JOB_ID/sources" \
  -H "Authorization: Bearer REPLACE_WITH_TOKEN" \
  -H "Idempotency-Key: 2f8c1e40-source-01" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "REPLACE_WITH_UPLOAD_ID"}'

curl "$EPISODIC_BASE/v1/ingestion-jobs/$JOB_ID" \
  -H "Authorization: Bearer REPLACE_WITH_TOKEN"

Repeating any of those POST requests with the same idempotency key and the same canonical body replays the stored response. Reusing a key with a different body returns 409 Conflict. The key is scoped to the authenticated principal, so two clients cannot collide on one.

Read the source-to-script intake section of the users' guide

Not implemented

Endpoint families the design specifies and the application does not register.

  • Episodes and TEI. /v1/episodes and its TEI, lifecycle, and approval-event routes are roadmap step 4.2.
  • Quality artefacts. Retrieving evaluator findings and runtime estimates by episode is roadmap task 2.2.7.
  • Audio, preview, and export. Every audio route is roadmap phase 3.
  • Resumable uploads. POST /v1/uploads/init awaits an object-store adapter that can issue pre-signed URLs.
  • Event streaming. No WebSocket endpoint is registered; streaming is roadmap step 4.5.

Routes that existed before the /v1 prefix were treated as pre-release implementation details and carry no compatibility promise.

See where each of these sits in the roadmap