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

# Conceitos

> O modelo de dados por trás da API.

Tudo na API é um de poucos recursos. Entender como se relacionam deixa a
referência fácil de navegar.

## Items

Um **item** é uma fonte monitorada. O `type` é `youtube_channel`,
`youtube_video`, `twitter` ou `rss`. Você cria a partir de uma URL ou 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/@canal" }'
```

Um item `youtube_channel` **contém vídeos** (veja [Monitorar uma fonte](/pt/guides/monitor-a-source)).
Items são a unidade atômica — coleções os agrupam, reporters os processam,
transcripts e documents são produzidos a partir deles.

## Coleções

Uma **coleção** agrupa items. Tem `visibility` (`private` | `public`) e flags
`expose_*` que controlam quais seções não-donos veem quando é pública. Uma
coleção também pode ser **paga** (`price_coins` > 0) — fãs assinam pra liberar o
conteúdo. Veja [Coleções](/pt/guides/collections) e
[Coleções pagas](/pt/guides/paid-collections).

## Reporters, workflows, steps

Um **reporter** é um agente. Ele tem um ou mais **workflows**; um workflow é uma
lista ordenada de **steps**, cada um um `tool_id` mais um prompt inline e params.
Um workflow tem um `target_kind` (`youtube_video`, `youtube_channel` ou
`collection`) que decide contra o quê você roda.

```
reporter ──▶ workflow ──▶ [ step(tool+prompt), step, … ]
```

Rodar um workflow sobre uma fonte produz **documents** (ex.: resumos). Veja
[Montar um reporter](/pt/guides/build-a-reporter).

## Schedules

Um **schedule** pertence a um reporter e roda um dos workflows dele numa cadência
(`interval_hours`) sobre um conjunto de `collection_ids`. Vídeos novos nessas
coleções são processados automaticamente. Veja [Agendar execuções](/pt/guides/schedule-runs).

## Executions

Qualquer execução — um transcript, um workflow manual, uma rodada agendada — cria
uma **execution** com status (`pending` → `running` → `done` | `error`). Os
endpoints de escrita retornam `202` com a execution; você acompanha até concluir.
Isso é central o bastante pra ter página própria: [Operações assíncronas](/pt/async-operations).

## Transcripts & documents

* **Transcripts** — texto de um vídeo, um por idioma. Gerados de forma assíncrona
  (chama um transcriber externo); leia com `GET /v1/items/{id}/transcript`.
* **Documents** — saída de workflow (resumos, análises). Liste com
  `GET /v1/documents`, filtre por `item_id`, `reporter_id`, `kind`.

## Search, discover, events

* **Search** — busca semântica nos seus transcripts e documents
  (`GET /v1/search?q=…`).
* **Discover** — o catálogo público (`/v1/discover/*`): coleções, reporters e
  perfis de usuário públicos.
* **Events** — seu feed de atividade (`GET /v1/events`), também transmitido pelo
  WebSocket de realtime.

## Convenções

Leia uma vez — valem pra API inteira.

### Erros

Respostas não-2xx têm um único shape:

```json theme={null}
{ "erro": "mensagem legível" }
```

| Status | Significado                                                     |
| ------ | --------------------------------------------------------------- |
| `400`  | Request inválido (campo ausente/inválido).                      |
| `401`  | Crachá ausente/inválido.                                        |
| `402`  | Sem saldo (chamada com API key) — veja [Cobrança](/pt/billing). |
| `403`  | Autenticado mas sem permissão (rota admin-only).                |
| `404`  | Não encontrado, ou sem acesso.                                  |
| `409`  | Conflito (ex.: já assinado).                                    |

Falha de rede (o request nem chegou ao servidor) é sinalizada pelos clientes como
status `0` — distinto de qualquer erro HTTP.

### Paginação

Endpoints de lista aceitam `limit` e `offset` na query (ex.:
`GET /v1/items?limit=50&offset=100`). Defaults e tetos variam por rota — veja a
referência.

### IDs e idioma

IDs de recurso são strings opacas (UUIDs). Onde há conteúdo multilíngue,
`language` é `pt` ou `en`; muitos endpoints de lista aceitam `?lang=` pra filtrar.