Referência da API

Configurações e reset

A linha única da instalação, e a rota que apaga tudo.

Uma linha só, para a instalação inteira. O catálogo de cada toggle está em Configurações.

GET/api/settings

Papel: Administrador

As configurações da instalação: a linha única que vale para todos os espaços.

Requisição

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

Resposta200

{
  "allowCrossProjectLinks": false,
  "cardInfoDisplay": "MODAL",
  "cardIdVisibility": "ALWAYS",
  "epicsEnabled": true,
  "createDefaultAction": "CARD",
  "calendarEnabled": true,
  "epicReorderEnabled": true,
  "uploadMode": "ALL",
  "tenantCreationEnabled": true,
  "columnManagementEnabled": true,
  "columnScope": "TENANT",
  "backupScheduleMode": "DAILY",
  "backupScheduleTime": "08:30",
  "backupScheduleWeekdays": [],
  "backupScheduleCron": null
}

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.

PATCH/api/settings

Papel: Administrador

Edita as configurações. Campo ausente não é tocado.

Corpo da requisição

Campo	Tipo	Descrição
`allowCrossProjectLinks`	`boolean`
`cardInfoDisplay`	`enum`	ACCORDION · MODAL
`cardIdVisibility`	`enum`	ALWAYS · HOVER
`epicsEnabled`	`boolean`	Desligar apaga todos os epics, e por isso exige a frase.
`createDefaultAction`	`enum`	CARD · PROJECT · EPIC
`calendarEnabled`	`boolean`
`epicReorderEnabled`	`boolean`
`uploadMode`	`enum`	`NONE` não apaga anexo nenhum: vale para uploads novos.NONE · IMAGE · ALL
`tenantCreationEnabled`	`boolean`
`columnManagementEnabled`	`boolean`
`columnScope`	`enum`	Trocar realoca os cards nas colunas do novo conjunto, na mesma transação.TENANT · PROJECT
`backupSchedule`	`objeto`	Entra como OBJETO (`mode`, `time`, `weekdays`, `cron`) e rearma o timer. `WEEKLY` sem dia e `CRON` sem expressão não têm próxima ocorrência.
`confirm`	`"REMOVER EPICS"`	Só acompanhando `epicsEnabled: false`.

Requisição

# o agendamento entra INTEIRO, e não campo a campo
curl -s -X PATCH http://localhost:3000/api/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backupSchedule": {
      "mode": "WEEKLY",
      "time": "03:00",
      "weekdays": [1, 4],
      "cron": null
    }
  }'

# desligar epics APAGA todos eles: por isso a frase
curl -s -X PATCH http://localhost:3000/api/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "epicsEnabled": false, "confirm": "REMOVER EPICS" }'

Resposta200

{
  "allowCrossProjectLinks": false,
  "cardInfoDisplay": "MODAL",
  "cardIdVisibility": "ALWAYS",
  "epicsEnabled": true,
  "createDefaultAction": "CARD",
  "calendarEnabled": true,
  "epicReorderEnabled": true,
  "uploadMode": "ALL",
  "tenantCreationEnabled": true,
  "columnManagementEnabled": true,
  "columnScope": "TENANT",
  "backupScheduleMode": "WEEKLY",
  "backupScheduleTime": "03:00",
  "backupScheduleWeekdays": [1, 4],
  "backupScheduleCron": null
}

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 instalação está em modo demonstração, e ali backup, armazenamento e contas ficam fora do ar.
`422`	A frase de confirmação não veio, ou veio diferente. Rota destrutiva exige a frase exata no corpo.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

POST/api/reset

Papel: Administrador

Apaga TUDO: cards, projetos, epics, etiquetas, espaços e os arquivos.

As contas não são apagadas: quem apaga usuário é /api/users/[id]. A resposta traz quantos registros caíram de cada tabela.

Corpo da requisição

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

Requisição

curl -s -X POST http://localhost:3000/api/reset \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "APAGAR TUDO" }'

Resposta200

{
  "cards": 42,
  "projects": 3,
  "epics": 5,
  "tags": 8,
  "relations": 11,
  "comments": 27,
  "attachments": 14,
  "tenants": 2,
  "columns": 10
}

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 instalação está em modo demonstração, e ali backup, armazenamento e contas ficam fora do ar.
`422`	A frase de confirmação não veio, ou veio diferente. Rota destrutiva exige a frase exata no corpo.