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

# Busca semântica

> Busque nos transcripts e documents da sua biblioteca.

A busca roda **semanticamente** (por significado, não palavra-chave) sobre o
conteúdo com embedding da sua biblioteca — transcripts e documents de workflow.

## Faça uma busca

```bash theme={null}
curl "https://api.clipping.cc/v1/search?q=o%20que%20falaram%20sobre%20preço&top_k=10" \
  -H "Authorization: Bearer ck_live_…"
```

```json theme={null}
{
  "q": "o que falaram sobre preço",
  "count": 3,
  "hits": [
    {
      "chunk_id": "…",
      "score": 0.82,
      "item_id": "itm_…",
      "source_type": "transcript",
      "text": "…o plano começa em…",
      "start_seconds": 142.0,
      "end_seconds": 158.5,
      "collection_ids": ["col_…"]
    }
  ]
}
```

Cada hit aponta de volta pro `item_id` (e `start_seconds` pra transcripts de
vídeo, pra você deep-linkar no momento exato).

## Refinando

| Param           | Efeito                                 |
| --------------- | -------------------------------------- |
| `q`             | a query (obrigatório)                  |
| `top_k`         | máximo de resultados (default 10)      |
| `collection_id` | restringe a uma coleção                |
| `reporter_id`   | restringe aos documents de um reporter |
| `item_id`       | restringe a um item                    |
| `source_type`   | ex.: `transcript` vs tipos de document |

## O que é pesquisável

Só conteúdo com **embedding** é indexado. Torne pesquisável:

* transcrevendo com `embed: true` (veja [Transcrever](/pt/guides/transcribe)), ou
* rodando um [workflow de reporter](/pt/guides/build-a-reporter) que produz
  documents.

<Note>
  A busca gera embedding da sua query a cada chamada, então custa um pouco mais
  que uma leitura simples (`0,005 coin`).
</Note>

## Nuvem de tags

Pra uma visão mais leve e facetada de um pedaço da biblioteca,
`GET /v1/tags?collection_id=…` (ou `?item_id=…`) devolve as tags em destaque —
útil pra UIs de navegação.