Guia da API

A API do East Agile Tracker é projetada tanto para agentes quanto para humanos. Tudo o que você pode fazer na interface, você pode fazer pela API — e algumas coisas que a interface não expõe também estão lá.

Este guia leva você do zero a “fazer scripts do seu backlog” em menos de dez minutos. Para a referência completa de endpoints, veja a Especificação da API.

Três tipos de credenciais

Você se autentica com uma chave no cabeçalho X-TrackerToken. Há dois tipos de chave que você mesmo emite, e um terceiro que um cliente MCP obtém para você:

Chaves de usuário (ea_user_…) — Atuam como você. Crie-as em Account Settings → API Keys. Use-as para scripts pessoais, ferramentas de CLI, integrações.
Chaves de agente (ea_agent_…) — Atuam como um agente nomeado em um projeto. Crie-as em Project Settings → Agents. Use-as para agentes de IA — Claude Code, Codex, o seu próprio — que devem participar do projeto como colegas de equipe nomeados.
Tokens MCP (ea_mcp_…) — Tokens de acesso OAuth 2.1 emitidos para um cliente MCP (Claude, uma IDE) depois que você o aprova na página de consentimento. Eles atuam como você, e você pode revogá-los em Account Settings → Connected apps.

A caixa de diálogo única após criar uma chave de API pessoal nas configurações da conta, com a chave mascarada nesta captura

O formulário de criação de chave da aba Agent com um nome e o papel member selecionado, abaixo das instruções de configuração

As diferenças entre os dois que você mesmo emite:

	Chave de usuário	Chave de agente
Escopo	Todos os seus projetos	Um projeto específico
Identidade na trilha de auditoria	Seu nome	O nome do agente
Papel	Seu papel em cada projeto	Definido na criação da chave (viewer, member ou manager — nunca acima do papel do próprio membro que a emite)
Revogação	Revogue uma chave; você mantém o acesso por outras chaves/sessões	Revogue ou rotacione uma chave; o agente perde o acesso imediatamente
Melhor para	Automação pessoal, scripts	Agentes de IA que devem ser distinguíveis de você no histórico

Authorization: Bearer … também funciona, se você preferir esse estilo de cabeçalho.

Olá, API

Obtenha seus projetos:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Ou, para uma chave de agente, liste o projeto a que ela está restrita:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

A API é JSON, no estilo REST, versionada em /api/v1/. Os mesmos formatos para humanos e agentes.

Criar um projeto

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

A resposta inclui o project_id e quaisquer padrões que o servidor aplicou (escala de estimativa, estado pronto, etc.).

Criar uma história

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate é o rótulo do valor da escala, como string — "3", ou "13" na escala Fibonacci — porque ele precisa corresponder a um ponto da escala do projeto. Um número JSON é rejeitado.

Mover uma história pelo ciclo de vida

O endpoint de transição valida o movimento solicitado e retorna os próximos estados permitidos em caso de erro:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

O campo é to (não to_state). Se o movimento for ilegal — digamos que você tentou pular de unstarted direto para accepted — a resposta é 422 invalid_transition com detalhes de erro estruturados:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] }
}

Esta é uma das pequenas coisas que tornam a API amigável a agentes: um agente pode ler details.allowed e escolher o próximo movimento certo sem precisar extrair texto.

rejected é terminal para o endpoint de transição. Para colocar uma história rejeitada de volta ao trabalho, POST …/stories/{sid}/restart; POST …/stories/{sid}/reject é a forma verbal de rejeitar uma história entregue.

Comentar em uma história

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

O comentário é atribuído a quem possui a chave de API — se for uma chave de agente, o autor do comentário é o agente.

Escritas idempotentes

Todo endpoint de escrita aceita um cabeçalho Idempotency-Key. Tente novamente com a mesma chave e o mesmo corpo, e receba de volta a mesma resposta. Tente novamente com a mesma chave e um corpo diferente, e receba um 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

Isso é crítico para agentes em loops de repetição — falhou no meio de uma escrita, tente novamente com a mesma chave, sem histórias duplicadas.

Transições em massa

Mova muitas histórias de uma vez. Cada história é julgada de forma independente; um movimento ilegal não faz as outras falharem.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

Acompanhar o fluxo de eventos

Para agentes que querem reagir ao que os humanos fazem, faça polling do endpoint de eventos:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

A resposta é um fluxo de eventos paginado por cursor, com o ator, o recurso e a mudança. Cada evento tem um ID; passe o último ID que você viu como since para retomar de onde parou. Sem webhooks, sem extração de texto, sem eventos perdidos. O fluxo exige o papel member — um viewer recebe 403.

Buscar com a sintaxe de filtro

GET /projects/{id}/search?q=<query> executa uma poderosa busca full-text + estruturada sobre as histórias do projeto. A linguagem de consulta é modelada nos qualificadores de busca de issues do GitHub — então a sintaxe que você (ou um agente de IA) já conhece do GitHub se aplica quase toda aqui.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

A resposta é um envelope JSON, com as histórias ordenadas por relevância:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total é a contagem completa de correspondências, não o tamanho da página. Pagine com limit (padrão 50, máx. 1000) e offset; ordene com sort=relevance (padrão), created, created_asc, updated ou state.

Gramática

Texto livre corresponde ao título, à referência e à descrição de uma história (full-text, com stemming e ranqueamento). Coloque uma frase exata entre "aspas".
Qualificadores são field:value. Separe alternativas por vírgula (OU dentro de um mesmo campo): type:bug,chore. Separe qualificadores por espaço (E entre eles).
Negue qualquer termo ou qualificador com um - inicial: -label:wontfix.
Intervalos para datas e pontos: inclusivo a..b, ou aberto >x / <x.

Qualificadores

Qualificador	Exemplo	Corresponde a
`type:`	`type:bug,chore`	tipo(s) de história
`state:`	`state:started,finished`	estado(s) do fluxo de trabalho
`label:`	`label:"my label"`	uma label
`epic:`	`epic:"Checkout"`	histórias de um épico
`priority:`	`priority:p1`	prioridade
`points:`	`points:3` · `points:1..5` · `points:>3`	valor ou intervalo de estimativa
`iteration:`	`iteration:42`	id da iteração
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	uma data ou intervalo (granularidade de dia); `release:` é a data de release da história
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	uma pessoa por nome ou e-mail — membros e agentes, `mention:` incluído; `@me` é você
`has:blocker`	`has:blocker`	tem um bloqueio aberto
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	um sinalizador

mywork: é um alias de owner: — mywork:me equivale a owner:@me. O antigo qualificador scheduled: foi aposentado e é ignorado silenciosamente; use release:.

O OU por vírgula (type:bug,chore) vale para os qualificadores de faceta; os qualificadores de pessoas (owner: requester: follower: reviewer: commenter: mention:) aceitam um único valor.

Exemplos

payment crash                              texto livre "payment" E "crash"
"exact phrase"                             uma frase
type:bug,chore state:started               bugs ou chores que estão started
owner:@me -label:wontfix                   minhas, excluindo a label wontfix
points:3..8 created:2026-05-01..2026-06-01 estimadas 3-8, criadas em maio
follower:tomas has:blocker                 tomas a segue e ela está bloqueada
is:backlog updated:>2026-06-01             itens do backlog tocados desde 1º de junho

A mesma string de consulta move a caixa de busca do quadro (que abre uma coluna de resultados ao vivo) e esta API — uma só gramática para humanos e agentes. Buscar no conteúdo de comentários, tarefas e bloqueios está no roadmap; hoje o texto livre cobre o título, a referência e a descrição da própria história.

Descobrir a API

A especificação OpenAPI 3 ao vivo está em:

https://api.eastagiletracker.com/api/v1/openapi.json

O Swagger UI está em:

https://api.eastagiletracker.com/api/v1/docs/

/openapi.json e /docs não são autenticados — um agente pode ler o contrato antes de ter uma chave. Uma vez que ele possua uma chave, /api/v1/meta (que requer uma chave válida) retorna sua identidade e o grafo de transições por tipo de história; as consultas de dados de referência (/story_types, /story_states, /effort_scales, /priority_scales) também não são autenticadas. Juntas, elas permitem que os agentes respondam “o que posso fazer aqui?” sem 403s por tentativa e erro.

O openapi.json servido traz os esquemas de corpo de requisição dos endpoints de escrita, incluindo o maxLength de cada campo, para que um cliente possa validar antes de enviar. A Especificação resume esses mesmos formatos.

Controle por WebSocket

Para automação interativa — comandar uma sessão de navegador logada a partir de um script, ou controlar remotamente a interface para tutoriais — há um canal WebSocket:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

O token é o JWT da sessão do navegador, não uma chave de API — uma chave ea_user_* ou ea_agent_* é recusada antes do upgrade. A maioria dos usuários nunca precisa disso; ele está lá para os casos em que o REST não é suficiente.

Importar de outro tracker

Se você está fazendo o script de uma migração em massa:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

Fontes de arquivo suportadas: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (a exportação própria do East Agile Tracker — o formato de round-trip). O endpoint multipart roda de forma síncrona e responde com as contagens do resultado.

GitHub importa a partir da API em vez de um arquivo, pelo endpoint JSON — sem file, apenas as coordenadas do repositório:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

O endpoint JSON é assíncrono: ele responde 202 com { "import_id", "status" } e você faz polling em GET /projects/{id}/imports/{import_id} até o job chegar a done ou failed. Só uma importação roda por projeto de cada vez — uma segunda chamada enquanto outra está em andamento dá 409 import_already_running. O ciclo inteiro, com os campos de progresso do job, está em Popular um projeto a partir de um repositório do GitHub.

O token é opcional na requisição, mas a busca em si sempre se autentica — ela corre na API GraphQL do GitHub, que não tem camada anônima. Omita token e o servidor substitui pelo seu token de plataforma: apenas repositórios públicos, compartilhado por todos os chamadores e recusado com import_github_shared_quota_low quando o orçamento GraphQL cai abaixo de 500 pontos. Um repositório privado, ou um deployment que não configurou token de plataforma (import_github_no_token), exige o seu. Seja qual for o token usado, ele serve apenas para as chamadas ao GitHub e nunca é armazenado ou devolvido. O detalhe completo, incluindo o teto REST sem autenticação de 60 requisições do GitHub, está em Popular um projeto a partir de um repositório do GitHub.

Prévia em modo dry-run. Adicione "dry_run": true (JSON) ou -F "dry_run=true" (multipart) a qualquer fonte. A importação analisa, resolve e remove duplicatas exatamente como uma execução real, retorna as mesmas contagens de resultado (imported, skipped, errors, unmatched) e então reverte tudo — nada é escrito. No endpoint JSON, as contagens chegam pelo job consultado, seja dry run ou não.

Limites. O corpo de um upload é limitado a 10 MiB, e uma única importação a 5.000 histórias; exceder qualquer um é um 400 sem nada escrito. Reimportar um arquivo é seguro — linhas já importadas (correspondidas pelo id de origem) são ignoradas, não duplicadas.

Exportar um projeto

Qualquer papel de projeto pode listar os formatos; baixar um é exclusivo do owner:

# Os formatos de exportação registrados: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Baixe um formato (eat é o CSV de round-trip com fidelidade total)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Ids de formato de intercâmbio: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, além dos formatos de documento pdf e docx. Todo anexo pode ser baixado como um único zip a partir de GET /projects/{id}/export/attachments.

Formato de erro

Todos os erros são JSON com, no mínimo:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

Muitas respostas de erro também incluem um objeto details — details.fields (um array com os nomes dos campos problemáticos) em validation_failed, e details.allowed (ao lado de from/to) em 422 invalid_transition. Use-os. Um 429 rate_limited traz um cabeçalho Retry-After no mesmo envelope JSON.

Paginação

Os endpoints de listagem aceitam limit e cursor. O cursor é opaco; passe o next_cursor da resposta anterior. O teto de limit é por endpoint — 200 em histórias, comentários e projetos, 500 em eventos, 1000 na busca e no audit log. Uma listagem simples (sem cursor) que precisou truncar a resposta avisa isso nos cabeçalhos: X-Tracker-Pagination-Truncated, -Limit, -Offset e -Next-Offset, que você devolve como offset= para a próxima página. Não há cabeçalho de contagem total.

O que vem a seguir

Especificação da API — Cada endpoint, cada verbo, cada formato.
Instruções de Operação → Agentes — Lado da interface: emitir chaves de agente, nomear agentes, revogar.
Introdução — Conceitos por trás da API: histórias, estados, iterações, velocidade, agentes.