Skip to main content

The Crumbcast API

Everything you do in a Crumbcast project's dashboard, your own code can do through the API: upload and import videos, edit and organise them, run live streams, sign playback for your viewers, and hear back from Crumbcast through webhooks.

A project's dashboard in Crumbcast

Who these docs are for​

Developers who build Crumbcast into their own product or tools:

  • Backend developers putting videos and live streams on their site or in their app: uploading what their users send, signing playback for who may watch, keeping their own records in step through webhooks.
  • Teams automating their video work: importing from a link, publishing from CI, captioning, cutting and organising videos in bulk.
  • Builders of AI agents that work with a project's videos, through the API or its MCP server.

If you only use the dashboard, you don't need any of this: start with Using the dashboard.

What you need​

  • A Crumbcast account, and a project you're an admin of (to make API tokens) or a member of (to be given one).
  • An API token for that project, with the role your code needs: viewer to read, editor to upload and change videos, admin for signing keys, webhooks and the project's other settings.
  • Anything that sends HTTPS requests: curl, your language's HTTP client, or one of the SDKs, for JavaScript and TypeScript (npm install crumbcast), Python (pip install crumbcast) and PHP (composer require crumbcast/crumbcast). The guides' examples are curl, so they read the same in any language; the SDK pages show the same tasks in theirs.

What the API doesn't do​

A token works in its own project only. Your account, your organisation, its storages and billing, and the project itself (its members, its API tokens) are managed in the dashboard, not through the API.

How these docs are organised​

Base URL​

Every endpoint is under /api/v1/ on your Crumbcast's address:

https://your-crumbcast/api/v1/

Paths end in a slash (/api/v1/videos/{id}/), as the API reference lists them.

Requests and answers​

  • Requests and answers are JSON (Content-Type: application/json), but for the few that send or return a file.
  • IDs are UUIDs (3f2b9c1e-…). Links in the app and on watch pages show them shorter; the API takes and answers only the full form.
  • Times are ISO 8601, in UTC.
  • Fields are only ever added to answers: ignore ones you don't know.
  • Lists come in an object, under the plural of what they list ({"videos": [...]}), so they can gain fields too.

Paths and methods​

  • What's in a project is listed and made under it (/api/v1/projects/{project_id}/videos/); each one then has its own path (/api/v1/videos/{id}/), whatever project it's in.
  • PATCH changes only the fields sent; PUT replaces what's at the path with what's sent (a player's settings, a video's protection).
  • What isn't a change of fields is a POST to the action's own path (/api/v1/videos/{id}/trim/, /api/v1/webhooks/{id}/test/).

Where to start​

  1. Make an API token in your project's settings, and install the JavaScript, Python or PHP SDK if you use one of them.
  2. Upload a video, or import one from a link.
  3. Hear when it's ready with a webhook, rather than asking again and again.
  4. For videos only some may watch, sign playback tokens from your backend.

The API reference has every endpoint a token can call, generated from the API's OpenAPI spec, which is also at /api/v1/openapi.public.json for generating a client in your language.