API do Backlog — visão geral

A API do Backlog é uma API REST para agentes de IA e integrações lerem e escreverem atividades, projetos e comentários da sua organização.

Para que serve

• Listar projetos e atividades com filtros (status, prioridade, responsável, prazo).
• Criar e atualizar atividades, incluindo checklist, prioridade, prazo e vínculos.
• Ler e adicionar comentários em nome de um agente.
• Listar os membros da organização para usar como responsáveis.

Autenticação

Toda chamada usa a chave de API da organização.

• Formato da chave: começa com bk_.
• Envio no header: Authorization: Bearer SUA_CHAVE ou x-api-key: SUA_CHAVE.
• A chave identifica a organização: você só acessa dados da própria organização.
• Sem chave válida a API responde 401 com {"error": "..."}.

Como gerar a chave

1. Abra Configurações → API & MCP (apenas administradores da organização).
2. Clique em Gerar chave de API e copie o valor exibido.
3. Use a chave nos seus agentes e integrações.

Atenção: Regenerar invalida a chave anterior imediatamente. Revogar desativa o acesso até que uma nova chave seja gerada.

URL base e documentação

• A URL base é o endereço onde você usa o Backlog (ex.: https://<seu-dominio>).
• Documentação interativa (Scalar) com todos os parâmetros: /api-docs.
• Especificação OpenAPI 3.1 em JSON: /api/openapi.json (exige sessão de usuário logado).
• O JSON de sucesso sempre traz o bloco org com o id e o name da organização autenticada.

Endpoints disponíveis

Observação: os caminhos em português existem como facilidade, mas a criação e a exclusão de atividades estão apenas em /api/v1/tasks e /api/v1/tasks/{id}, respectivamente.

Filtros de listagem de atividades

Enviados como query string em GET /api/v1/atividades:

• project_id — ID do projeto.
• status — nome exato da coluna, por exemplo Backlog ou Em progresso.
• priority — low, medium, high ou urgent.
• type — tipo da atividade, por exemplo task, bug, epic.
• assignee_email — e-mail do responsável.
• search — busca no título ou no código da atividade.
• due_before e due_after — faixa de prazo no formato YYYY-MM-DD.
• include_done — true inclui as concluídas (padrão false).
• sort — created_desc, due_asc ou priority_desc.
• limit — de 1 a 500 (padrão 100).
• offset — paginação.

Criar atividade (corpo do POST /api/v1/tasks)

Campos aceitos:

• project_id (obrigatório) — ID do projeto.
• title (obrigatório) — título da atividade.
• description, acceptance_criteria — descrição e critérios de aceite.
• priority — low, medium, high ou urgent (padrão medium).
• due_date — YYYY-MM-DD.
• status — nome exato da coluna; se omitido, usa a primeira coluna do tipo "todo".
• type — task, bug, epic, improvement ou campaign (padrão task).
• checklist, labels — itens iniciais e etiquetas por nome (criadas se não existirem).
• assignee_ids — IDs de membros retornados por GET /api/v1/users.
• client_id, product_id, module_id, feature_id — vínculos, sempre dentro da própria organização.

O código da atividade (por exemplo TEC-12) é gerado automaticamente pelo contador do projeto.

Atualizar atividade (PATCH /api/v1/tasks/{id})

Aceita os mesmos campos da criação, além de:

• status — precisa ser o nome de uma coluna existente no board do projeto, senão retorna 400.
• checklist — substitui todos os itens atuais.
• labels — substitui todas as etiquetas atuais.
• assignee_ids — substitui todos os responsáveis; o primeiro vira o responsável principal.
• client_id, product_id, module_id, feature_id, service_id, service_module_id, service_feature_id — enviar null remove o vínculo.

Referências fora da organização são rejeitadas com 400.

Exemplos

Listar atividades urgentes:

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://SEU_DOMINIO/api/v1/tasks?priority=urgent&limit=10"

Criar uma atividade:

curl -X POST -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"ID_DO_PROJETO","title":"Revisar contrato","priority":"high"}' \
  "https://SEU_DOMINIO/api/v1/tasks"

Comentar em uma atividade:

curl -X POST -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"body":"Validado em produção.","author":"Agente IA"}' \
  "https://SEU_DOMINIO/api/v1/atividades/ID_DA_ATIVIDADE/comentarios"

Erros comuns

• 401 — chave de API inválida, ausente ou revogada.
• 400 — corpo inválido ou campo obrigatório faltando.
• 404 — atividade, projeto ou cliente não existe na organização autenticada.
• 500 — falha interna; tente novamente e, se persistir, acione o suporte.

Boas práticas

• Use limit e offset para paginar em vez de baixar tudo de uma vez.
• Trate 401 como chave expirada e peça uma nova ao administrador.
• Nunca exponha a chave em código de frontend, repositórios ou logs.
• Se o agente já suporta Model Context Protocol, prefira o MCP: ele já encapsula estas chamadas.