Referência da API

Projetos

O rótulo de filtro dentro do espaço de trabalho.

Projeto não isola nada: quem isola é o espaço. Apagar um projeto libera os cards e leva os epics junto.

GET/api/projects

Papel: LeitorEspaço de trabalho

Os projetos 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/projects?tenant=cmsp4djx60002p801o7ybpkv7" \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmttg1vjy000zlf015g097nhi",
    "name": "Integrações",
    "description": "Consumo da API por outros sistemas",
    "color": "sky",
    "position": 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 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/projects

Papel: MembroEspaço de trabalho

Cria um projeto.

Corpo da requisição

Campo	Tipo	Descrição
`tenantId`obrigatório	`cuid`	Obrigatório: não existe projeto fora de um espaço de trabalho.
`name`obrigatório	`string`
`description`	`string \| null`
`color`	`acento ou #rrggbb`	Aceita um dos 8 acentos ou um `#rrggbb`.Ausente: sugerido pelo servidor

Requisição

curl -s -X POST http://localhost:3000/api/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "cmsp4djx60002p801o7ybpkv7",
    "name": "Integrações",
    "description": "Consumo da API por outros sistemas",
    "color": "sky"
  }'

Resposta201

{
  "id": "cmttg1vjy000zlf015g097nhi",
  "name": "Integrações",
  "description": "Consumo da API por outros sistemas",
  "color": "sky",
  "position": 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 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/projects/[id]

Papel: MembroEspaço de trabalho

Renomeia, recolore ou descreve um projeto.

Parâmetros de rota

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

Corpo da requisição

Campo	Tipo	Descrição
`name`	`string`
`description`	`string \| null`
`color`	`acento ou #rrggbb`

Requisição

curl -s -X PATCH http://localhost:3000/api/projects/cmttg1vjy000zlf015g097nhi \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Consumo da API por outros sistemas e integrações." }'

Resposta200

{
  "id": "cmttg1vjy000zlf015g097nhi",
  "name": "Integrações",
  "description": "Consumo da API por outros sistemas e integrações.",
  "color": "sky",
  "position": 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 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`	O corpo veio vazio. Campo ausente significa não mexe, então um `PATCH` sem nenhum campo não teria efeito nenhum.

Sem tenantId: o espaço é escolhido na criação e nunca muda.

DELETE/api/projects/[id]

Papel: MembroEspaço de trabalho

Apaga um projeto. Os cards são LIBERADOS; os epics vão junto.

O projectId do card é anulável, então os cards voltam para “Sem projeto”. O epic, ao contrário, não existe fora de um projeto, e por isso vai junto.

Parâmetros de rota

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

Requisição

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

Resposta200

{ "deleted": true, "cardsReleased": 4 }

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.