Referência da API

Espaços de trabalho

A raiz da hierarquia. Prefixo de administrador.

Um espaço novo nasce com as 5 colunas padrão. Apagar leva tudo que está dentro, e por isso a rota exige a frase no corpo.

GET/api/tenants

Papel: Administrador

Os espaços de trabalho da instalação, com a contagem de cards e projetos.

Requisição

curl -s http://localhost:3000/api/tenants \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmsp4djx60002p801o7ybpkv7",
    "name": "Pessoal",
    "color": "amber",
    "position": 0,
    "cardCount": 12,
    "projectCount": 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 conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.

POST/api/tenants

Papel: Administrador

Cria um espaço de trabalho, já com as 5 colunas padrão.

Corpo da requisição

Campo	Tipo	Descrição
`name`obrigatório	`string`
`color`	`acento ou #rrggbb`	Ausente: sugerido pelo servidor

Requisição

curl -s -X POST http://localhost:3000/api/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Rascunho Docs", "color": "lilac" }'

Resposta201

{
  "id": "cmttg1vbw000slf01380evq0t",
  "name": "Rascunho Docs",
  "color": "lilac",
  "position": 3,
  "cardCount": 0,
  "projectCount": 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 é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`403`	A criação de espaços está desligada nas Configurações. Os que existem seguem inteiros.
`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.

Não há seed: as colunas padrão nascem com cada espaço, na mesma transação.

PATCH/api/tenants/[id]

Papel: Administrador

Renomeia ou recolore um espaço de trabalho.

Parâmetros de rota

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

Corpo da requisição

Campo	Tipo	Descrição
`name`	`string`
`color`	`acento ou #rrggbb`

Requisição

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

Resposta200

{
  "id": "cmsp4djx60002p801o7ybpkv7",
  "name": "Pessoal",
  "color": "stone",
  "position": 0,
  "cardCount": 12,
  "projectCount": 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 conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`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/tenants/[id]

Papel: Administrador

Apaga o espaço e TUDO que está dentro dele.

Cards, projetos, epics, etiquetas, comentários e os arquivos no volume. A frase no corpo é obrigatória: a confirmação da interface é uma camada por cima, nunca a única.

Parâmetros de rota

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

Corpo da requisição

Campo	Tipo	Descrição
`confirm`obrigatório	`"APAGAR TENANT"`	Exatamente `APAGAR TENANT`.

Requisição

curl -s -X DELETE http://localhost:3000/api/tenants/cmttg1vbw000slf01380evq0t \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "APAGAR TENANT" }'

Resposta200

{
  "deleted": true,
  "name": "Rascunho Docs",
  "cards": 1,
  "projects": 1
}

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 é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`404`	O recurso não existe, ou já foi apagado.
`422`	Sempre sobra um espaço de trabalho: o último não é apagado.
`422`	A frase de confirmação não veio, ou veio diferente. Rota destrutiva exige a frase exata no corpo.

O último espaço não é apagado, e a conferência acontece DENTRO da transação, para que duas requisições simultâneas não passem as duas.

PATCH/api/tenants/order

Papel: Administrador

Reordena os espaços de trabalho: subconjunto, como os epics.

Corpo da requisição

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

Requisição

curl -s -X PATCH http://localhost:3000/api/tenants/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantIds": [
      "tenant-pessoal",
      "cmsp4djx60002p801o7ybpkv7"
    ]
  }'

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 conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`404`	O recurso não existe, ou já foi apagado.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.