---
name: catcher-data-wiki
description: Use quando um app ou agente precisa consumir o Wiki do Catcher (/v1/cloudwiki/*). Base de conhecimento RAG — páginas Markdown, busca híbrida, ask com fontes, Knowledge Refinery.
homepage: https://catcher.one/produtos/wiki
docs: https://catcher.one/docs/wiki
api_base: https://data-api.catcher.one
---

# Catcher — Wiki

Autenticação: `X-API-Key: ctc_…` (owner/admin). Base: https://data-api.catcher.one. Onboarding de key
e conceitos gerais: https://catcher.one/skill. Referência navegável: https://catcher.one/docs/wiki.

# Wiki — base de conhecimento com RAG (`cloudwiki`)

> Rotas `/v1/cloudwiki/*` · owner/admin · gated por `CLOUDWIKI_ENABLED` (off → 404)

## O que é

Uma **base de conhecimento gerenciada**: espaços de páginas em Markdown
(frontmatter + corpo), organizados em pastas, com **busca híbrida**
(semântica + lexical), **perguntas com resposta fundamentada** (`ask`, RAG com
fontes citadas), **ingestão de arquivos** e o **Knowledge Refinery** — um
destilador assíncrono que transforma o espaço em FAQ cards. Cada página é
indexada **na escrita** (sem passo de rebuild).

## O que dá pra fazer

- Criar **espaços** por projeto (opcionalmente por tenant) e organizá-los em
  **pastas** numa árvore.
- **Upsert de páginas** por path (`PUT …/pages/<path>`) com Markdown — a página
  fica pesquisável na hora.
- **Buscar** (`search`) com fusão híbrida RRF e **perguntar** (`ask`) com
  resposta fundamentada + páginas-fonte.
- **Ingerir arquivos** (PDF, DOCX, MD…) como fontes do espaço, com re-chunk,
  habilitar/desabilitar e reindexar.
- Rodar o **Refinery** (FAQ cards destilados) e listar os cards.
- Auditar: **graph** de wikilinks (resolvidos/quebrados) e **audit** (páginas
  sem fonte, links quebrados, órfãs).

## Fluxo em 5 minutos

```bash
KEY="X-API-Key: ctc_…" ; B=https://data-api.catcher.one ; JS='Content-Type: application/json'

# 1. Criar um espaço no projeto
SID=$(curl -sX POST $B/v1/cloudwiki/projects/$PID/spaces -H "$KEY" -H "$JS" \
  -d '{ "name": "Base de conhecimento" }' | jq -r .id)

# 2. Escrever uma página (indexada na hora)
curl -sX PUT "$B/v1/cloudwiki/spaces/$SID/pages/politicas/reembolso" -H "$KEY" -H "$JS" \
  -d '{ "markdown": "---\ntitle: Política de reembolso\n---\n\n# Política de reembolso\n\nPlano anual: 30 dias…" }'

# 3. Buscar (híbrido)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/search -H "$KEY" -H "$JS" \
  -d '{ "q": "reembolso plano anual", "hybrid": true, "limit": 5 }'

# 4. Perguntar (RAG com fontes)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/ask -H "$KEY" -H "$JS" \
  -d '{ "question": "qual o prazo de reembolso do plano anual?" }'
# → { "answer": "…", "sources": [{ "path": "politicas/reembolso", … }] }

# 5. Ingerir um arquivo como fonte (multipart)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/sources -H "$KEY" \
  -F "file=@contrato-padrao.pdf"
```

## Busca e ask — parâmetros

`POST /v1/cloudwiki/spaces/{sid}/search`:

| Campo | Tipo | O que faz |
|---|---|---|
| `q` | string | A consulta. |
| `hybrid` | bool | Funde o braço semântico (cosine/pgvector) com o lexical (FTS) por **RRF** antes do corte — recomendado; resolve termo exato (ID, SKU, código) que o cosine enterra. |
| `qa_first` | bool | Prefere FAQ cards destilados (Refinery) antes de chunks crus. |
| `limit` | int | Máximo de hits. |
| `lexical_weight` | float 0..1 | Inclina a fusão para o braço lexical (default 0.5). |
| `rerank` | bool | Re-rank listwise com LLM dos candidatos over-fetched (opt-in — custa uma chamada de modelo). |
| `k_overfetch` | int | Quantos candidatos buscar antes do re-rank (default 20). |
| `path_prefixes` | []string | Escopa a busca a paths que começam com os prefixos (ex.: `["politicas/"]`). |

Cada hit informa **como** foi encontrado: `match: "semantic" | "lexical" |
"both"` — debug de retrieval é parte do contrato.

`POST /v1/cloudwiki/spaces/{sid}/ask` aceita `question` + os mesmos ajustes
(`qa_first`, `lexical_weight`, `rerank`, `k_overfetch`, `path_prefixes`); a
recuperação do RAG é sempre híbrida. A resposta traz `answer` + `sources`.

## Fontes (arquivos ingeridos)

| Rota | O que faz |
|---|---|
| `POST /spaces/{sid}/sources` (multipart `file=`) | Ingere: converte para Markdown, chunka e indexa. |
| `GET /spaces/{sid}/sources` | Lista (filename, status, chunks, enabled). |
| `GET /spaces/{sid}/sources/{srcid}` | Detalhe: Markdown convertido + chunks. |
| `PATCH /spaces/{sid}/sources/{srcid}` `{enabled}` | Liga/desliga a fonte no retrieval (desabilitada = guardada mas fora da busca). |
| `POST /spaces/{sid}/sources/{srcid}/reindex` | Re-chunk + re-embed mantendo o id. |
| `DELETE /spaces/{sid}/sources/{srcid}` | Remove a fonte e seus chunks. |

## Knowledge Refinery (FAQ cards)

O Refinery destila o espaço em **cards de pergunta-resposta** com fontes — um
processo assíncrono com status acompanhável:

```bash
curl -sX POST $B/v1/cloudwiki/spaces/$SID/refinery/runs -H "$KEY"      # dispara
curl -s $B/v1/cloudwiki/spaces/$SID/refinery/runs -H "$KEY"           # status dos runs
curl -s $B/v1/cloudwiki/spaces/$SID/faq -H "$KEY"                     # cards prontos
```

Com `qa_first: true` na busca/ask, perguntas recorrentes acertam o card direto
em vez de costurar chunks. Config por espaço em
`GET/PATCH /spaces/{sid}/refinery/config`.

## Organização e governança

- **Árvore**: `GET /projects/{pid}/tree` (pastas + espaços);
  `POST/GET/DELETE /projects/{pid}/folders`; `PATCH /spaces/{sid}` renomeia/move.
- **Graph**: `GET /spaces/{sid}/graph` — arestas de wikilinks
  (`[[caminho/da-pagina]]`), resolvidos e quebrados.
- **Audit**: `GET /spaces/{sid}/audit` — páginas sem fonte, links quebrados,
  órfãs. Meta saudável: tudo zero.

## Boas práticas

- **Páginas são síntese**, não transcript: uma página por conceito, com
  wikilinks entre vizinhas — o graph/audit é seu detector de deriva.
- **Escreva na mesma operação em que aprendeu**: a página já sai indexada; não
  existe "rebuild depois".
- Para agentes de IA, exponha o espaço via **[MCP](mcp.md)** (`wiki_ask`,
  `wiki_search`, `wiki_upsert_page`) com escopos `wiki:read`/`wiki:write`.