Referência da API

Backup

Gerar, guardar, inspecionar e restaurar o `.zip`.

São oito rotas, todas de administrador e todas fora do ar no modo demonstração.

Não existe GET /api/backup/export

A exportação é um job: POST /api/backup/job agenda, GET /api/backup/job acompanha e GET /api/backup/file baixa quando ficar pronto.

GET/api/backup/job

Papel: Administrador

O estado da exportação: status, destino, tamanho e quando ficou pronta.

A exportação é um JOB, e não um download síncrono: um .zip com o volume inteiro não cabe no tempo de uma requisição.

Requisição

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

Resposta200

{
  "status": "SENT",
  "origin": "MANUAL",
  "destination": "S3",
  "location": "backups/notebugs-backup-2026-09-08T22-39-26.zip",
  "requestedAt": "2026-09-09T01:38:55.706Z",
  "startsAt": "2026-09-09T01:39:25.706Z",
  "readyAt": "2026-09-09T01:39:27.980Z",
  "expiresAt": null,
  "downloadedAt": null,
  "filename": "notebugs-backup-2026-09-08T22-39-26.zip",
  "size": 28092801,
  "missingFiles": 0,
  "error": 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.

SENT significa que o arquivo foi para o bucket, e por isso /api/backup/file recusa nesse estado.

POST/api/backup/job

Papel: Administrador

Agenda a geração de um backup.

Corpo da requisição

Campo	Tipo	Descrição
`destination`	`enum`	`LOCAL` grava no container; `S3` manda para o bucket. Ausente usa o que estiver configurado.LOCAL · S3Ausente: o destino configurado

Requisição

curl -s -X POST http://localhost:3000/api/backup/job \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "S3" }'

// O backup é um JOB: o arquivo só existe quando status chega a READY.
await fetch("http://localhost:3000/api/backup/job", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ destination: "LOCAL" }),
});

let job;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const response = await fetch("http://localhost:3000/api/backup/job", {
    headers: { Authorization: `Bearer ${token}` },
  });
  job = await response.json();
} while (job.status === "PENDING" || job.status === "RUNNING");

Resposta200

{
  "status": "PENDING",
  "origin": "MANUAL",
  "destination": "S3",
  "location": "backups/notebugs-backup-2026-09-08T22-39-26.zip",
  "requestedAt": "2026-09-09T01:38:55.706Z",
  "startsAt": "2026-09-09T01:39:25.706Z",
  "readyAt": null,
  "expiresAt": null,
  "downloadedAt": null,
  "filename": "notebugs-backup-2026-09-08T22-39-26.zip",
  "size": null,
  "missingFiles": 0,
  "error": 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.
`409`	Já existe uma exportação em curso.
`422`	O destino `S3` foi pedido, mas não há bucket configurado para backups.

O .zip que fica no container tem nome fixo, uma cópia e prazo; o que vai para o bucket tem nome com hora, acumula e não expira.

DELETE/api/backup/job

Papel: Administrador

Cancela a exportação em curso, ou descarta o arquivo pronto.

Requisição

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

Resposta200

{
  "status": "IDLE",
  "origin": null,
  "destination": null,
  "location": null,
  "requestedAt": null,
  "startsAt": null,
  "readyAt": null,
  "expiresAt": null,
  "downloadedAt": null,
  "filename": null,
  "size": null,
  "missingFiles": 0,
  "error": 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.

GET/api/backup/schedule

Papel: Administrador

O backup automático: modo, expressão efetiva, próxima e última execução, e o fuso do container.

Só leitura. Quem GRAVA o agendamento é PATCH /api/settings; a próxima execução não é configuração: ela sai do timer do processo.

Requisição

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

Resposta200

{
  "mode": "DAILY",
  "time": "08:30",
  "weekdays": [],
  "cron": "30 8 * * *",
  "timezone": "America/Sao_Paulo",
  "nextRunAt": "2026-09-09T11:30:00.000Z",
  "lastRunAt": null,
  "lastResult": 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.

Mensagem de erro e payload nunca trazem data formatada: o container roda em UTC e erraria o dia. Quem formata é o cliente.

GET/api/backup/file

Papel: Administrador

Baixa o .zip pronto que está no container.

Requisição

curl -s -o notebugs-backup.zip \
  http://localhost:3000/api/backup/file \
  -H "Authorization: Bearer $TOKEN"

Resposta200

content-type: application/zip
content-disposition: attachment; filename="notebugs-backup-2026-09-08T22-39-26.zip"

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.
`409`	Não há `.zip` pronto para baixar. `SENT` também recusa: o arquivo está no bucket, e não no container.

409 fora de READY, e SENT não é READY, porque ali o arquivo está no bucket. Para esses, use /api/backup/remote e restaure por remote.

GET/api/backup/remote

Papel: Administrador

Os .zip que já estão no bucket, do mais novo para o mais antigo.

Requisição

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

Resposta200

[
  {
    "name": "notebugs-backup-2026-09-08T22-39-26.zip",
    "size": 28092801,
    "uploadedAt": "2026-09-08T22:39:31.000Z"
  }
]

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.
`409`	O bucket configurado não guarda backups: o escopo em vigor manda o `.zip` para o disco.

O name vem sem prefixo: é exatamente o que se manda de volta no campo remote da inspeção e da restauração.

POST/api/backup/inspect

Papel: Administradormultipart/form-data

Lê um backup e responde o que a restauração FARIA. Não grava byte nenhum.

Devolve a versão do formato, um bloco por espaço de trabalho com a contagem de cada escopo, os anexos que não seriam recriados e como as contas do arquivo se comparam às de hoje.

Corpo da requisição

Campo	Tipo	Descrição
`file`	`arquivo (.zip)`	O `.zip` enviado no multipart.
`remote`	`string`	O nome de um backup do bucket, baixado no SERVIDOR.

Requisição

# do disco…
curl -s -X POST http://localhost:3000/api/backup/inspect \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]"

# …ou de um que já está no bucket. Nunca os dois: isso é 400.
curl -s -X POST http://localhost:3000/api/backup/inspect \
  -H "Authorization: Bearer $TOKEN" \
  -F "remote=notebugs-backup-2026-09-08T22-39-26.zip"

Resposta200

{
  "version": 18,
  "exportedAt": "2026-09-08T22:39:26.000Z",
  "tenants": [
    {
      "id": "cmsp4djx60002p801o7ybpkv7",
      "name": "Pessoal",
      "counts": { "projects": 2, "epics": 5, "cards": 42, "tags": 8, "templates": 1, "relations": 11, "comments": 27, "history": 96, "attachments": 14 }
    }
  ],
  "skippedFiles": [],
  "users": { "file": 3, "current": 3 },
  "settings": { "columnScope": "TENANT", "epicsEnabled": true }
}

Respostas de erro

Código	Quando acontece
`400`	Vieram `file` e `remote` na mesma requisição. É um ou outro, nunca os dois.
`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`	O `.zip` não é um backup do NoteBugs, está corrompido ou é de uma versão que esta instalação não lê.

file e remote nunca vêm juntos: os dois é 400. Origem remota não afrouxa validação nenhuma: dali para baixo só há bytes.

POST/api/backup/import

Papel: Administradormultipart/form-data

Restaura um backup, inteiro ou recortado por espaço de trabalho.

Corpo da requisição

Campo	Tipo	Descrição
`file`	`arquivo (.zip)`
`remote`	`string`
`selection`	`JSON`	JSON com os escopos POR espaço do arquivo, mais `settings` e `users`. É o que a tela manda.
`scopes`	`JSON (forma antiga)`	A forma antiga: uma lista plana de escopos, aplicada a todos os espaços do arquivo. Continua aceita.

Requisição

# restaura tudo: sem selection nem scopes
curl -s -X POST http://localhost:3000/api/backup/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]"

# seleção por espaço de trabalho: é o que a tela manda
curl -s -X POST http://localhost:3000/api/backup/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "remote=notebugs-backup-2026-09-08T22-39-26.zip" \
  -F 'selection={
    "tenants": {
      "cmsp4djx60002p801o7ybpkv7": ["projects", "cards", "comments"]
    },
    "settings": false,
    "users": false
  }'

Resposta200

{
  "projects": 2,
  "epics": 0,
  "tags": 0,
  "templates": 0,
  "cards": 42,
  "relations": 0,
  "comments": 27,
  "history": 0,
  "attachments": 0,
  "tenants": 1,
  "scopes": ["projects", "cards", "comments"],
  "settings": false,
  "users": 0,
  "skippedFiles": []
}

Respostas de erro

Código	Quando acontece
`400`	Vieram `file` e `remote` na mesma requisição. É um ou outro, nunca os dois.
`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`	O `.zip` não é um backup do NoteBugs, está corrompido ou é de uma versão que esta instalação não lê.
`422`	A seleção pede um escopo sem o de que ele depende: `epics` sem `projects`, `comments` sem `cards`.

Sem selection nem scopes, restaura tudo, menos as contas, que exigem pedido explícito (users: true): restaurar contas troca quem alcança a instalação.