Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clipping.cc/llms.txt

Use this file to discover all available pages before exploring further.

Some operations call external providers (a transcriber, an LLM, the YouTube API) and can take seconds to minutes. Instead of blocking, these endpoints accept the work and return immediately with HTTP 202 and an execution you track to completion.

​
Which endpoints are async

EndpointReturns
POST /v1/items/{id}/transcript202 { execution }
POST /v1/reporters/{id}/process202 { execution }
POST /v1/reporters/{id}/process-collection202 { execution }
POST /v1/reporters/{id}/schedules/{sid}/run202 { status, schedule_id }
Everything else (reads, CRUD on collections/reporters/workflows/schedules) is synchronous — it returns the final result directly.

​
The execution lifecycle

pending ──▶ running ──▶ done
                   └──▶ error
The 202 body gives you an execution with an execution_id and an initial status: 
{ "execution": { "execution_id": "exc_…", "status": "pending" } }

​
Tracking to completion (polling)

Poll the execution until it leaves pending/running: 
curl https://api.clipping.cc/v1/executions/exc_123 \
  -H "Authorization: Bearer ck_live_…"
The detail response includes the execution, the workflow that ran, per-step summaries (LLM input/output), and step_inputs for steps not yet run.
To see everything currently in flight, call GET /v1/executions/me?active=1 — it returns only pending/running executions. Handy for a dashboard or a “still working” indicator.

​
Realtime (app only)

The web app doesn’t poll — it subscribes to the realtime WebSocket (wss://api.clipping.cc/v1/realtime?token=<jwt>) and receives event messages as executions progress.
The WebSocket authenticates with a session JWT only (in the token query param) — an API key cannot open it. If you’re integrating with an API key, poll GET /v1/executions/{id} as shown above.

​
Cost

The 202 itself draws the route’s flat fee (e.g. 0.01 coin for running a transcript). The real provider cost is drawn as pass-through from the resource owner while the job runs — so a job can still end in 402 if the owner runs out of balance mid-flight.