Guida API

L’API di East Agile Tracker è progettata tanto per gli agenti quanto per gli umani. Tutto ciò che puoi fare nell’interfaccia, puoi farlo via API — e alcune cose che l’interfaccia non espone sono lì anch’esse.

Questa guida ti porta da zero allo “scripting del tuo backlog” in meno di dieci minuti. Per il riferimento completo degli endpoint, vedi Specifica API.

Due tipi di chiavi

Ti autentichi con una chiave API nell’header X-TrackerToken. Ci sono due tipi:

• Chiavi utente (ea_user_…) — Agiscono come te. Creale in Account Settings → API Keys. Usale per script personali, strumenti da CLI, integrazioni.
• Chiavi agente (ea_agent_…) — Agiscono come un agente con nome in un progetto. Creale come owner del progetto in Project Settings → Agents. Usale per agenti IA — Claude Code, Codex, il tuo — che dovrebbero partecipare al progetto come compagni di squadra con nome.

Le differenze:

	Chiave utente	Chiave agente
Ambito	Tutti i tuoi progetti	Un progetto specifico
Identità nell’audit log	Il tuo nome	Il nome dell’agente
Ruolo	Il tuo ruolo in ciascun progetto	Impostato alla creazione della chiave (viewer o member)
Revoca	Revoca una chiave; mantieni l’accesso tramite altre chiavi/sessioni	Revoca una chiave; l’agente perde immediatamente l’accesso
Ideale per	Automazione personale, script	Agenti IA che dovrebbero essere distinguibili da te nella cronologia

Authorization: Bearer … funziona anche se preferisci quello stile di header.

Ciao, API

Ottieni i tuoi progetti:

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

Oppure, per una chiave agente, elenca il progetto a cui è vincolata:

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

L’API è JSON, in stile REST, versionata su /api/v1/. Stesse forme per umani e agenti.

Creare un progetto

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 risposta include il project_id ed eventuali default applicati dal server (scala di stima, done state, ecc.).

Creare una storia

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

Far muovere una storia lungo il ciclo di vita

L’endpoint di transizione valida il movimento richiesto e restituisce gli stati successivi consentiti in caso di errore:

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

Il campo è to (non to_state). Se il movimento è illegale — diciamo che hai provato a saltare da unstarted dritto ad accepted — la risposta è 422 invalid_transition con dettagli d’errore strutturati:

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

Questa è una delle piccole cose che rendono l’API a misura di agente: un agente può leggere details.allowed e scegliere il movimento successivo giusto senza dover analizzare prosa.

Commentare una storia

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

Il commento è attribuito a chiunque possieda la chiave API — se è una chiave agente, l’autore del commento è l’agente.

Scritture idempotenti

Ogni endpoint di scrittura accetta un header Idempotency-Key. Riprova la stessa chiave con lo stesso body e riottieni la stessa risposta. Riprova la stessa chiave con un body diverso e ottieni 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" }'

Questo è cruciale per gli agenti nei loop di retry — vai in crash a metà scrittura, riprova con la stessa chiave, nessuna storia duplicata.

Transizioni in blocco

Sposta molte storie in una sola volta. Ogni storia è giudicata indipendentemente; un movimento illegale non fa fallire gli altri.

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

Seguire lo stream di eventi

Per gli agenti che vogliono reagire a ciò che fanno gli umani, fai il polling dell’endpoint degli eventi:

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 risposta è uno stream di eventi paginato a cursore con l’attore, la risorsa e la modifica. Ogni evento ha un ID; passa l’ultimo ID che hai visto come since per riprendere da dove avevi lasciato. Nessun webhook, nessuno scraping, nessun evento perso.

Cercare con la sintassi dei filtri

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

Filtri disponibili:

Filtro	Esempio	Descrizione
type:	type:feature	Filtra per tipo di storia
state:	state:started	Filtra per stato
label:	label:"my label"	Filtra per label
owner:	owner:claire	Filtra per owner
requester:	requester:tomas	Filtra per requestor
has:	has:blocker	Storie con blocker
is:	is:unestimated	Feature non stimate

Il testo libero corrisponde a titolo e descrizione. Combina i filtri separandoli con spazi — sono in AND.

Scoprire l’API

La spec OpenAPI 3 live è su:

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

Swagger UI è su:

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

/openapi.json e /docs non sono autenticati — un agente può leggere il contratto prima di avere una chiave. Una volta che ne possiede una, /api/v1/meta (che richiede una chiave valida) restituisce la sua identità e il grafo delle transizioni per ciascun tipo di storia; anche i lookup dei dati di riferimento (/story_types, /story_states, /effort_scales) non sono autenticati. Insieme consentono agli agenti di rispondere a “cosa posso fare qui?” senza 403 per tentativi ed errori.

Nota: l’openapi.json servito elenca i path ma attualmente fornisce request body vuoti — usa le forme dei campi nella Specifica per le scritture.

Controllo WebSocket

Per l’automazione interattiva — pilotare una sessione browser autenticata da uno script, o controllare a distanza l’interfaccia per i tutorial — c’è un canale WebSocket:

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

La maggior parte degli utenti non ne ha mai bisogno; è lì per i casi in cui REST non basta.

Importare da un altro tracker

Se stai facendo lo scripting di una migrazione in blocco:

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"

Sorgenti supportate: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Formato degli errori

Tutti gli errori sono JSON con come minimo:

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

Molte risposte d’errore includono anche un oggetto details — details.fields (un array di nomi di campo offendenti) su validation_failed, e details.allowed (accanto a from/to) su 422 invalid_transition. Usali.

Paginazione

Gli endpoint di elenco accettano limit e cursor. Il cursore è opaco; passa il next_cursor della risposta precedente. Gli header di risposta includono anche X-Tracker-Pagination-Total per i conteggi totali dove è economico calcolarli.

Cosa viene dopo

• Specifica API — Ogni endpoint, ogni verbo, ogni forma.
• Istruzioni operative → Agenti — Lato interfaccia: generare chiavi agente, dare nomi agli agenti, revocare.
• Introduzione — Concetti dietro l’API: storie, stati, iterazioni, velocity, agenti.