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.

Dois tipos de chave

Você se autentica com uma chave de API no cabeçalho X-TrackerToken. Há dois tipos:

• 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 como owner do projeto 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.

As diferenças:

	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 ou member)
Revogação	Revogue uma chave; você mantém o acesso por outras chaves/sessões	Revogue 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"]
  }'

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.

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.created" \
  -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.

Buscar com a sintaxe de filtro

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Filtros disponíveis:

Filtro	Exemplo	Descrição
type:	type:feature	Filtrar por tipo de história
state:	state:started	Filtrar por estado
label:	label:"my label"	Filtrar por label
owner:	owner:claire	Filtrar por dono
requester:	requester:tomas	Filtrar por solicitante
has:	has:blocker	Histórias com bloqueios
is:	is:unestimated	Features não estimadas

O texto livre corresponde ao título e à descrição. Combine filtros separando-os por espaço — eles são unidos com E (AND).

Descobrir a API

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

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

O Swagger UI está em:

https://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) 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.

Observação: o openapi.json servido lista os caminhos, mas atualmente vem com corpos de requisição vazios — use os formatos de campo da Especificação para escritas.

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=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

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 suportadas: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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.

Paginação

Os endpoints de listagem aceitam limit e cursor. O cursor é opaco; passe o next_cursor da resposta anterior. Os cabeçalhos de resposta também incluem X-Tracker-Pagination-Total para contagens totais quando for barato de calcular.

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.