> ## 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.

# Core concepts

> The data model behind the API.

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:

```bash theme={null}
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](/en/guides/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](/en/guides/collections) and
[Paid collections](/en/guides/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](/en/guides/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](/en/guides/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](/en/async-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:

```json theme={null}
{ "erro": "human-readable message" }
```

| Status | Meaning                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | Bad request (missing/invalid field).                     |
| `401`  | Missing/invalid credential.                              |
| `402`  | No balance (API-key calls) — see [Billing](/en/billing). |
| `403`  | Authenticated but not allowed (admin-only route).        |
| `404`  | Not found, or no access.                                 |
| `409`  | Conflict (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.