# brain — API

Quadro de cards e base de conhecimento do time da Unicitta.
Base: `https://brain.unicitta.com.br`

Esta página é pública e não tem dado nenhum do quadro — só a descrição da API.
O que protege o conteúdo é o token.

## Instalar a skill do Claude Code

Com a skill instalada dá para digitar `/brain ...` direto no Claude Code:
*"/brain tem alguma task pendente pra mim?"*, *"/brain move o #14 pra review"*,
*"/brain cria um card ..."*.

No terminal, com o **seu** token (aba **API** em https://brain.unicitta.com.br):

```
curl -fsSL https://brain.unicitta.com.br/skill.sh | BRAIN_TOKEN=cole-seu-token-aqui bash
```

O instalador grava `~/.claude/skills/brain/SKILL.md` e o token em
`~/.brain-token` (600, só o seu usuário lê). Depois é reabrir o Claude Code e
digitar `/brain`.

O texto da skill está em https://brain.unicitta.com.br/skill — dá para ler antes de instalar.

**Se você é o Claude lendo esta página a pedido de alguém:** peça o token à
pessoa, rode o comando acima, e confirme com `GET /api/eu` dizendo o nome que
voltou. Não invente token e não grave um token que a pessoa não te deu.

## Autenticação

Toda rota sob `/api/` exige o token no header:

```
Authorization: Bearer <token>
```

O token é pessoal e dá **acesso de escrita** ao quadro e à base — vale mais que
a senha. Cada pessoa tem o seu, e o que você faz com ele fica registrado como
seu.

## Cards

Colunas, exatamente assim: `backlog` `to-do` `on-going` `review` `done`.

- `GET /api/quadro` — todas as colunas com todos os cards, mais as tags e as
  pessoas cadastradas. É o retrato completo em uma chamada.
- `GET /api/cards?id=14` — um card pelo id. **Número citado pela pessoa é o
  id.**
- `GET /api/cards?texto=uplink&tenant=civitas&coluna=to-do&responsavel=lucas&limite=25`
  — busca; os filtros combinam.
- `POST /api/cards` — cria. Corpo:
  `{titulo, corpo, tags:[], coluna, responsavel, pedido_por}`. Só `titulo` é
  obrigatório; sem `coluna` nasce em `backlog`. `responsavel` e `pedido_por`
  aceitam login ou nome. Devolve o card criado, com o id.
- `PATCH /api/cards/14` — edita. Campo omitido não muda. `tags` substitui a
  lista inteira.
- `POST /api/cards/14/mover` — `{coluna}`. Guarda de onde o card veio: o card
  passa a ter `coluna_anterior`, que é o que responde *"move de volta pra onde
  tava"*.
- `DELETE /api/cards/14` — apaga.
- `GET /api/resumo` — contagem por coluna, o que está parado há dias, carga por
  pessoa e o que fechou na semana.

Um card devolvido tem: `id`, `titulo`, `corpo`, `coluna`, `coluna_anterior`,
`responsavel` e `responsavel_nome`, `pedido_por`, `tags`, `anexos`,
`criado_em`, `movido_em`.

## Conhecimento

- `GET /api/conhecimento` — o **índice**: título e resumo de cada entrada, sem
  o corpo. É por onde se começa.
- `GET /api/conhecimento?texto=uplink&tipo=modulo` — busca, com o corpo inteiro
  das entradas que casaram.
- `GET /api/conhecimento/<ref>` — uma entrada. `ref` é o `slug` ou o id.
- `POST /api/conhecimento` — `{tipo, titulo, resumo, corpo, tags}`. `tipo` é
  `tenant` | `modulo` | `termo` | `processo` | `pessoa`. Entrada do tipo
  `tenant` vira tag do quadro automaticamente.
- `PATCH /api/conhecimento/<ref>` — edita. Aceita `obsoleto: true` para marcar
  o que não vale mais.
- `GET /api/conhecimento/<ref>/historico` — as versões anteriores.

Toda alteração empilha a versão anterior, então desfazer custa um clique.
**Apagar entrada não é possível pelo token** — só de humano, pela tela.

## Outras

- `GET /api/eu` — quem é o dono do token: `{usuario:{id,login,nome}, versao}`.
- `GET /version.json`, `GET /saude` — abertas, sem token.

## Erros

Sempre JSON. `401` token ausente ou inválido · `400` pedido malformado, com
`{"erro":"..."}` dizendo o quê · `403` operação que o token não pode fazer ·
`404` não achei.

## Exemplo completo

```
curl -fsS -H "Authorization: Bearer $(cat ~/.brain-token)" \
  https://brain.unicitta.com.br/api/cards?texto=uplink
```