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.

Everything in the API is one of a few resources. Understanding how they relate makes the reference easy to navigate.

​
Items

An item is a monitored source. Its type is one of youtube_channel, youtube_video, twitter, or rss. You create one from a URL or handle: 
curl -X POST https://api.clipping.cc/v1/items \
  -H "Authorization: Bearer ck_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "source": "https://youtube.com/@channel" }'
A youtube_channel item contains videos (see Monitor a source). Items are the atomic unit — collections group them, reporters process them, transcripts and documents are produced from them.

​
Collections

A collection groups items. It has a visibility (private | public) and expose_* flags that control which sections are visible to non-owners when public. A collection can also be paid (price_coins > 0) — fans subscribe to unlock gated content. See Collections and Paid collections.

​
Reporters, workflows, steps

A reporter is an agent. It owns one or more workflows; a workflow is an ordered list of steps, each a tool_id plus an inline prompt and params. A workflow has a target_kind (youtube_video, youtube_channel, or collection) that decides what you run it against. 
reporter ──▶ workflow ──▶ [ step(tool+prompt), step, … ]
Running a workflow over a source produces documents (e.g. summaries). See Build a reporter.

​
Schedules

A schedule belongs to a reporter and runs one of its workflows on a cadence (interval_hours) over a set of collection_ids. New videos in those collections get processed automatically. See Schedule runs.

​
Executions

Any run — a transcript, a manual workflow, a scheduled run — creates an execution with a status (pending → running → done | error). Write endpoints return 202 with the execution; you track it to completion. This is central enough to have its own page: Asynchronous operations.

​
Transcripts & documents

  • Transcripts — text of a video, one per language. Generated asynchronously (it calls an external transcriber); read with GET /v1/items/{id}/transcript.
  • Documents — workflow output (summaries, analyses). List with GET /v1/documents, filter by item_id, reporter_id, kind.

​
Search, discover, events

  • Search — semantic search over your transcripts and documents (GET /v1/search?q=…).
  • Discover — the public catalog (/v1/discover/*): public collections, reporters and user profiles.
  • Events — your activity feed (GET /v1/events), also streamed over the realtime WebSocket.

​
Conventions

Read these once — they apply across the whole API.

​
Errors

Non-2xx responses share one shape: 
{ "erro": "human-readable message" }
StatusMeaning
400Bad request (missing/invalid field).
401Missing/invalid credential.
402No balance (API-key calls) — see Billing.
403Authenticated but not allowed (admin-only route).
404Not found, or no access.
409Conflict (e.g. already subscribed).
A network failure (request never reached the server) is surfaced by clients as status 0 — distinct from any HTTP error.

​
Pagination

List endpoints take limit and offset query params (e.g. GET /v1/items?limit=50&offset=100). Defaults and caps vary per route — see the reference.

​
IDs and language

Resource IDs are opaque strings (UUIDs). Where content is multilingual, language is pt or en; many list endpoints accept ?lang= to filter.