Referência da API

Modelos de card

O catálogo que pré-preenche um card novo.

A regra da composição é uma só: o que veio no pedido vence, o modelo preenche o que faltou. POST /api/cards com templateId se comporta exatamente como o formulário da interface.

GET/api/templates

Papel: LeitorEspaço de trabalho

Os modelos de card de um espaço de trabalho.

Parâmetros de query

Campo	Tipo	Descrição
`tenant`	`cuid`	Ausente: todos os espaços da pessoa

Requisição

curl -s "http://localhost:3000/api/templates?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmttg1vps0013lf01zl4o2xmp",
    "name": "Bug reportado",
    "title": "[BUG] ",
    "description": "## Passos\n1. \n\n## Esperado\n",
    "columnId": "cmttg1vdl000tlf01uuqhz8ad",
    "tagIds": ["cmttg1vnk0011lf01q0eswms5"]
  }
]

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.

POST/api/templates

Papel: MembroEspaço de trabalho

Cria um modelo de card.

Corpo da requisição

Campo	Tipo	Descrição
`tenantId`obrigatório	`cuid`
`name`obrigatório	`string`
`title`	`string \| null`	Título que o card ganha. Não é aparado: o espaço de um prefixo (`[BUG]` ) é conteúdo.
`description`	`string \| null`
`columnId`	`cuid \| null`	Precisa ser uma coluna do conjunto do TENANT.
`tagIds`	`cuid[]`	A lista FINAL de etiquetas do modelo.

Requisição

curl -s -X POST http://localhost:3000/api/templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "Bug reportado",
    "title": "[BUG] ",
    "description": "## Passos\n1. \n\n## Esperado\n",
    "columnId": "cmttg1vdl000tlf01uuqhz8ad",
    "tagIds": ["cmttg1vnk0011lf01q0eswms5"]
  }'

Resposta201

{
  "id": "cmttg1vps0013lf01zl4o2xmp",
  "name": "Bug reportado",
  "title": "[BUG] ",
  "description": "## Passos\n1. \n\n## Esperado\n",
  "columnId": "cmttg1vdl000tlf01uuqhz8ad",
  "tagIds": ["cmttg1vnk0011lf01q0eswms5"]
}

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.
`404`	O recurso não existe, ou já foi apagado.
`422`	A coluna do modelo precisa ser do conjunto do TENANT. Quem traduz para o conjunto do card na hora da criação é o servidor.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

O vazio no modelo ("", null, []) significa não define, nunca “apague”.

PATCH/api/templates/[id]

Papel: MembroEspaço de trabalho

Edita um modelo de card.

Parâmetros de rota

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

Corpo da requisição

Campo	Tipo	Descrição
`name`	`string`
`title`	`string \| null`
`description`	`string \| null`
`columnId`	`cuid \| null`
`tagIds`	`cuid[]`

Requisição

curl -s -X PATCH http://localhost:3000/api/templates/cmttg1vps0013lf01zl4o2xmp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Bug reportado (v2)" }'

Resposta200

{
  "id": "cmttg1vps0013lf01zl4o2xmp",
  "name": "Bug reportado (v2)",
  "title": "[BUG] ",
  "description": "## Passos\n1. \n\n## Esperado\n",
  "columnId": "cmttg1vdl000tlf01uuqhz8ad",
  "tagIds": ["cmttg1vnk0011lf01q0eswms5"]
}

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.
`404`	O recurso não existe, ou já foi apagado.
`422`	A coluna do modelo precisa ser do conjunto do TENANT. Quem traduz para o conjunto do card na hora da criação é o servidor.
`422`	O corpo veio vazio. Campo ausente significa não mexe, então um `PATCH` sem nenhum campo não teria efeito nenhum.

DELETE/api/templates/[id]

Papel: MembroEspaço de trabalho

Apaga o modelo. Os cards já criados a partir dele não são tocados.

Parâmetros de rota

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

Requisição

curl -s -X DELETE http://localhost:3000/api/templates/cmttg1vps0013lf01zl4o2xmp \
  -H "Authorization: Bearer $TOKEN"

Resposta200

{ "deleted": true }

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.
`404`	O recurso não existe, ou já foi apagado.