Guía de la API

La API de East Agile Tracker está diseñada tanto para agentes como para personas. Todo lo que puedes hacer en la UI lo puedes hacer por la API — y unas cuantas cosas que la UI no expone también están ahí.

Esta guía te lleva de cero a “scriptear tu backlog” en menos de diez minutos. Para la referencia completa de endpoints, consulta la Especificación de la API.

Dos tipos de claves

Te autenticas con una clave de API en la cabecera X-TrackerToken. Hay dos tipos:

• Claves de usuario (ea_user_…) — Actúan como tú. Créalas en Configuración de la cuenta → Claves de API. Úsalas para scripts personales, herramientas de CLI, integraciones.
• Claves de agente (ea_agent_…) — Actúan como un agente con nombre en un proyecto. Créalas como propietario del proyecto en Configuración del proyecto → Agentes. Úsalas para agentes de IA — Claude Code, Codex, el tuyo propio — que deban participar en el proyecto como compañeros de equipo con nombre.

Las diferencias:

	Clave de usuario	Clave de agente
Alcance	Todos tus proyectos	Un proyecto específico
Identidad en el registro de auditoría	Tu nombre	El nombre del agente
Rol	Tu rol en cada proyecto	Establecido al crear la clave (viewer o member)
Revocación	Revoca una clave; conservas el acceso mediante otras claves/sesiones	Revoca una clave; el agente pierde el acceso de inmediato
Ideal para	Automatización personal, scripts	Agentes de IA que deban distinguirse de ti en el historial

Authorization: Bearer … también funciona si prefieres ese estilo de cabecera.

Hello, API

Obtén tus proyectos:

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

O, para una clave de agente, lista el proyecto al que está limitada:

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

La API es JSON, de estilo REST, versionada en /api/v1/. Las mismas formas para personas y agentes.

Crear un proyecto

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
  }'

La respuesta incluye el project_id y cualquier valor por defecto que el servidor haya aplicado (escala de estimación, estado de finalización, etc.).

Crear una historia

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 una historia a lo largo de su ciclo de vida

El endpoint de transición valida el movimiento solicitado y, en caso de error, devuelve los estados siguientes permitidos:

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" }'

El campo es to (no to_state). Si el movimiento es ilegal — por ejemplo, si intentaste saltar de unstarted directamente a accepted — la respuesta es 422 invalid_transition con detalles de error estructurados:

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

Esta es una de las pequeñas cosas que hacen la API amigable para agentes: un agente puede leer details.allowed y elegir el siguiente movimiento correcto sin tener que rastrear texto.

Comentar en una historia

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." }'

El comentario se atribuye a quien sea el propietario de la clave de API — si es una clave de agente, el autor del comentario es el agente.

Escrituras idempotentes

Cada endpoint de escritura acepta una cabecera Idempotency-Key. Reintenta con la misma clave y el mismo cuerpo, y obtienes la misma respuesta. Reintenta con la misma clave y un cuerpo distinto, y obtienes un 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" }'

Esto es crítico para agentes en bucles de reintento — si se caen a mitad de una escritura, reintentan con la misma clave y no hay historias duplicadas.

Transiciones en lote

Mueve muchas historias a la vez. Cada historia se evalúa de forma independiente; un movimiento ilegal no hace fallar a las demás.

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"
  }'

Seguir el flujo de eventos

Para agentes que quieran reaccionar a lo que hacen las personas, sondea el 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"

La respuesta es un flujo de eventos paginado por cursor con el actor, el recurso y el cambio. Cada evento tiene un ID; pasa el último ID que viste como since para retomar donde lo dejaste. Sin webhooks, sin scraping, sin eventos perdidos.

Buscar con la sintaxis de filtros

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

Filtros disponibles:

Filtro	Ejemplo	Descripción
type:	type:feature	Filtrar por tipo de historia
state:	state:started	Filtrar por estado
label:	label:"my label"	Filtrar por etiqueta
owner:	owner:claire	Filtrar por propietario
requester:	requester:tomas	Filtrar por solicitante
has:	has:blocker	Historias con bloqueadores
is:	is:unestimated	Features sin estimar

El texto libre coincide con el título y la descripción. Combina filtros separándolos por espacios — se combinan con AND.

Descubrir la API

La especificación OpenAPI 3 en vivo está en:

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

Swagger UI está en:

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

/openapi.json y /docs no requieren autenticación — un agente puede leer el contrato antes de tener una clave. Una vez que tiene una clave, /api/v1/meta (que requiere una clave válida) devuelve su identidad y el grafo de transiciones por tipo de historia; las consultas de datos de referencia (/story_types, /story_states, /effort_scales) tampoco requieren autenticación. En conjunto, permiten a los agentes responder “¿qué puedo hacer aquí?” sin 403s de prueba y error.

Nota: el openapi.json servido lista las rutas pero actualmente entrega cuerpos de petición vacíos — usa las formas de los campos de la Especificación para las escrituras.

Control por WebSocket

Para automatización interactiva — controlar una sesión de navegador con sesión iniciada desde un script, o controlar la UI de forma remota para tutoriales — hay un canal WebSocket:

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

La mayoría de los usuarios nunca necesitan esto; está ahí para los casos en que REST no es suficiente.

Importar desde otro tracker

Si estás scripteando una migración masiva:

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"

Fuentes admitidas: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Formato de errores

Todos los errores son JSON con, como mínimo:

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

Muchas respuestas de error también incluyen un objeto details — details.fields (un array de nombres de campos infractores) en validation_failed, y details.allowed (junto a from/to) en 422 invalid_transition. Úsalos.

Paginación

Los endpoints de listado aceptan limit y cursor. El cursor es opaco; pasa el next_cursor de la respuesta anterior. Las cabeceras de respuesta también incluyen X-Tracker-Pagination-Total para los totales cuando es barato calcularlos.

Qué sigue

• Especificación de la API — Cada endpoint, cada verbo, cada forma.
• Instrucciones de operación → Agentes — Lado de la UI: crear claves de agente, nombrar agentes, revocar.
• Introducción — Conceptos detrás de la API: historias, estados, iteraciones, velocidad, agentes.