Referência da API

Etiquetas

O catálogo de etiquetas do espaço de trabalho.

Etiqueta é global dentro do espaço: não há etiqueta de projeto nem de epic, e ela não atravessa espaços.

GET/api/tags

Papel: LeitorEspaço de trabalho

O catálogo de etiquetas 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/tags?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmttg1vnk0011lf01q0eswms5",
    "name": "api",
    "color": "mint"
  }
]

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/tags

Papel: MembroEspaço de trabalho

Cria uma etiqueta.

Corpo da requisição

Campo	Tipo	Descrição
`tenantId`obrigatório	`cuid`
`name`obrigatório	`string`
`color`	`acento`	Só token de acento, sem hex livre, ao contrário de projeto e espaço.Ausente: sugerido pelo servidor

Requisição

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

Resposta201

{
  "id": "cmttg1vnk0011lf01q0eswms5",
  "name": "api",
  "color": "mint"
}

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.
`409`	Já existe um registro com esse nome dentro do mesmo espaço.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

PATCH/api/tags/[id]

Papel: MembroEspaço de trabalho

Renomeia ou recolore uma etiqueta.

Parâmetros de rota

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

Corpo da requisição

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

Requisição

curl -s -X PATCH http://localhost:3000/api/tags/cmttg1vnk0011lf01q0eswms5 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "color": "sage" }'

Resposta200

{
  "id": "cmttg1vnk0011lf01q0eswms5",
  "name": "api",
  "color": "sage"
}

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.
`409`	Já existe um registro com esse nome dentro do mesmo espaço.
`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/tags/[id]

Papel: MembroEspaço de trabalho

Apaga a etiqueta, tirando-a dos cards que a usavam.

Parâmetros de rota

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

Requisição

curl -s -X DELETE http://localhost:3000/api/tags/cmttg1vnk0011lf01q0eswms5 \
  -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.