Referência da API

Colunas

O conjunto, a marca de conclusão e a ordem.

Toda coluna pertence a um conjunto, e o conjunto é o par (tenantId, projectId). Qual deles vale para um card é decisão do columnScope das Configurações; ver Colunas e escopo.

GET/api/columns

Papel: LeitorEspaço de trabalho

As colunas de um espaço de trabalho.

Com ?project=, devolve apenas o conjunto EM VIGOR para um card daquele projeto, já resolvido pelo columnScope das Configurações.

Parâmetros de query

Campo	Tipo	Descrição
`tenant`	`cuid`	Sem ele, a rota devolve as colunas de todos os espaços que a conta alcança.Ausente: todos os espaços da pessoa
`project`	`cuid`	Recorta pelo conjunto daquele projeto. Só tem efeito junto de `tenant`.

Requisição

# todas as colunas do espaço: conjunto do tenant e de cada projeto
curl -s "http://localhost:3000/api/columns?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

# só o conjunto EM VIGOR para um card daquele projeto
curl -s "http://localhost:3000/api/columns?tenant=cmsp4djx60002p801o7ybpkv7&project=cmttg1vjy000zlf015g097nhi" \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmttg1vdl000tlf01uuqhz8ad",
    "projectId": null,
    "name": "A fazer",
    "accent": "stone",
    "position": 0,
    "done": false
  }
]

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não alcança o espaço de trabalho do recurso. É 403 e não 404 de propósito: assim a resposta não revela quais espaços existem.

Serve a quem chama a API de fora: a interface lê as colunas do payload de /api/board, que já vem escopado.

POST/api/columns

Papel: MembroEspaço de trabalho

Cria uma coluna no fim do conjunto.

Corpo da requisição

Campo	Tipo	Descrição
`tenantId`obrigatório	`cuid`
`projectId`	`cuid \| null`	Ausente ou nulo é o conjunto do TENANT, que serve também aos cards sem projeto.Ausente: conjunto do tenant
`name`obrigatório	`string`
`color`	`acento`	Só token de acento, sem hex livre.Ausente: sugerido pelo servidor
`done`	`boolean`	Marcar aqui já desliga a marca das demais do conjunto: há exatamente uma coluna de conclusão por conjunto.Ausente: false

Requisição

curl -s -X POST http://localhost:3000/api/columns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "Revisão",
    "color": "lilac"
  }'

Resposta201

{
  "id": "cmttg39e8001nlf01fmyfx43e",
  "projectId": null,
  "name": "Revisão",
  "accent": "lilac",
  "position": 5,
  "done": false
}

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A manipulação de colunas está desligada nas Configurações. Nenhuma coluna é apagada por isso: só a edição fica trancada.
`403`	A conta não alcança o espaço de trabalho do recurso. É 403 e não 404 de propósito: assim a resposta não revela quais espaços existem.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

PATCH/api/columns/[id]

Papel: MembroEspaço de trabalho

Renomeia, recolore ou transfere a marca de conclusão.

Parâmetros de rota

Campo	Tipo	Descrição
`id`obrigatório	`cuid`

Corpo da requisição

Campo	Tipo	Descrição
`name`	`string`
`color`	`acento`
`done`	`boolean`

Requisição

curl -s -X PATCH http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Em revisão", "color": "clay" }'

Resposta200

{
  "id": "cmttg39e8001nlf01fmyfx43e",
  "projectId": null,
  "name": "Em revisão",
  "accent": "clay",
  "position": 5,
  "done": false
}

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A manipulação de colunas está desligada nas Configurações. Nenhuma coluna é apagada por isso: só a edição fica trancada.
`404`	O recurso não existe, ou já foi apagado.
`422`	A marca de conclusão não se desmarca: ela se transfere. Marque outra coluna do conjunto.

O conjunto de uma coluna é IMUTÁVEL: nem tenantId nem projectId aparecem aqui.

DELETE/api/columns/[id]

Papel: MembroEspaço de trabalho

Apaga uma coluna, decidindo o que fazer com os cards dela.

Parâmetros de rota

Campo	Tipo	Descrição
`id`obrigatório	`cuid`

Corpo da requisição

Campo	Tipo	Descrição
`cards`	`enum`	`MOVE` manda os cards para outra coluna do mesmo conjunto; `DELETE` apaga os cards.MOVE · DELETE
`targetColumnId`	`cuid`	Obrigatório quando `cards` é `MOVE`.
`confirm`	`"APAGAR CARDS"`	Obrigatório quando `cards` é `DELETE`.

Requisição

# manda os cards para outra coluna do mesmo conjunto
curl -s -X DELETE http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": "MOVE",
    "targetColumnId": "cmttg1vdl000tlf01uuqhz8ad"
  }'

# apaga os cards junto, e por isso pede a frase
curl -s -X DELETE http://localhost:3000/api/columns/cmttg39e8001nlf01fmyfx43e \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cards": "DELETE", "confirm": "APAGAR CARDS" }'

Resposta200

{ "deleted": true, "cardsMoved": 0, "cardsDeleted": 0 }

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A manipulação de colunas está desligada nas Configurações. Nenhuma coluna é apagada por isso: só a edição fica trancada.
`404`	O recurso não existe, ou já foi apagado.
`422`	Todo conjunto termina com ao menos uma coluna, e uma delas conclui. Marque outra antes.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

A decisão é EXIGIDA: sem o campo cards, a rota recusa.

PATCH/api/columns/order

Papel: MembroEspaço de trabalho

Reordena colunas de um mesmo conjunto.

Recebe um SUBCONJUNTO: os ids informados assumem, nessa ordem, as posições que já ocupam juntos. É o que permite as setas mandarem só o par que trocou de lugar.

Corpo da requisição

Campo	Tipo	Descrição
`columnIds`obrigatório	`cuid[]`

Requisição

# um SUBCONJUNTO: os informados assumem as posições que já ocupam juntos
curl -s -X PATCH http://localhost:3000/api/columns/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "columnIds": [
      "cmttg1vdl000ulf01nhqhd23w",
      "cmttg1vdl000tlf01uuqhz8ad"
    ]
  }'

Resposta200

{ "updated": 2 }

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A manipulação de colunas está desligada nas Configurações. Nenhuma coluna é apagada por isso: só a edição fica trancada.
`404`	O recurso não existe, ou já foi apagado.
`422`	Os ids informados não pertencem todos ao mesmo conjunto. A rota recebe um subconjunto, mas ele precisa ser de um lugar só.