Referência da API

Convenções da API

O que vale para TODA rota. Leia antes de ler qualquer uma delas.

A API é HTTP com JSON, sem versionamento no caminho e sem SDK: http://localhost:3000/api/.... As regras abaixo valem para todas as rotas, sem exceção.

Credencial

Authorization: Bearer <token> para scripts, cookie de sessão para o navegador. As duas terminam na mesma identidade, e o cookie tem precedência. Detalhes em Autenticação.

Entrada

Toda entrada passa por schema. O que não casa é recusado com 422 e o campo details traz fieldErrors e formErrors, campo a campo.
Campo ausente não é tocado. Num PATCH, mandar só { favorite: true } mexe só nisso. Limpar exige valor explícito: null.
`tenantId` é imutável. Ele aparece na criação e em nenhum schema de edição.
Lista final vs. adiciona/remove: tagIds num card é a lista FINAL; no lote, as etiquetas viajam como addTagIds/removeTagIds.

Saída

Sucesso devolve o recurso serializado (ou { "deleted": true }, ou uma contagem). Falha devolve sempre a mesma forma:

{
  "error": "Dados inválidos.",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "name": ["Campo obrigatório."]
    }
  }
}

error é uma frase em pt-BR, escrita para quem está na tela. details só aparece nas recusas de schema. A lista completa está em Tratamento de erros.

Operação em lote recusa inteira

Nada é gravado pela metade

Um lote com 30 cards em que um deles quebra uma regra não grava os outros 29: a resposta é uma recusa só, e o estado não muda. Todos os espaços de trabalho envolvidos são conferidos antes.

Rota destrutiva exige a frase no corpo

Rota	Frase
`DELETE /api/tenants/[id]`	`APAGAR TENANT`
`DELETE /api/columns/[id]` com `cards: "DELETE"`	`APAGAR CARDS`
`PATCH /api/settings` com `epicsEnabled: false`	`REMOVER EPICS`
`POST /api/reset`	`APAGAR TUDO`

A confirmação da interface é uma camada por cima disso, nunca a única. O confirm é consumido na validação e não é gravado.

Precedência de segmento estático

bulk, epic e order têm precedência sobre [id] no roteamento. Nenhum recurso fica inalcançável por isso: os ids são cuid (ou fixos e legíveis, como tenant-pessoal), e nenhum deles é uma dessas palavras.

Não há paginação

As listagens devolvem o conjunto inteiro do filtro pedido, ordenado. O filtro que existe é o espaço de trabalho, e ele é aplicado no servidor.