Guide de l'API

L’API d’East Agile Tracker est conçue autant pour les agents que pour les humains. Tout ce que vous pouvez faire dans l’interface, vous pouvez le faire via l’API — et quelques fonctionnalités que l’interface n’expose pas y sont également disponibles.

Ce guide vous mène de zéro à « scripter votre backlog » en moins de dix minutes. Pour la référence complète des endpoints, voir la Spécification de l’API.

Deux types de clés

Vous vous authentifiez avec une clé d’API dans l’en-tête X-TrackerToken. Il en existe deux types :

• Clés utilisateur (ea_user_…) — Agissent en tant que vous. Créez-les dans Paramètres du compte → Clés d’API. Utilisez-les pour vos scripts personnels, vos outils en ligne de commande, vos intégrations.
• Clés d’agent (ea_agent_…) — Agissent en tant qu’agent nommé dans un projet. Créez-les en tant que propriétaire du projet dans Paramètres du projet → Agents. Utilisez-les pour les agents IA — Claude Code, Codex, le vôtre — qui doivent participer au projet en tant que coéquipiers nommés.

Les différences :

	Clé utilisateur	Clé d’agent
Portée	Tous vos projets	Un projet spécifique
Identité dans le journal d’audit	Votre nom	Le nom de l’agent
Rôle	Votre rôle dans chaque projet	Défini à la création de la clé (viewer ou member)
Révocation	Révoquez une clé ; vous conservez l’accès via d’autres clés/sessions	Révoquez une clé ; l’agent perd l’accès immédiatement
Idéal pour	Automatisation personnelle, scripts	Agents IA qui doivent être distinguables de vous dans l’historique

Authorization: Bearer … fonctionne aussi si vous préférez ce style d’en-tête.

Hello, API

Récupérez vos projets :

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

Ou, pour une clé d’agent, listez le projet auquel elle est rattachée :

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

L’API est en JSON, de style REST, versionnée à /api/v1/. Mêmes structures pour les humains et les agents.

Créer un projet

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 réponse inclut le project_id et toutes les valeurs par défaut appliquées par le serveur (échelle d’estimation, état « terminé », etc.).

Créer une story

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

Faire évoluer une story dans son cycle de vie

L’endpoint de transition valide le déplacement demandé et renvoie les états suivants autorisés en cas d’erreur :

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

Le champ est to (et non to_state). Si le déplacement est illégal — par exemple si vous tentez de passer directement de unstarted à accepted — la réponse est 422 invalid_transition avec des détails d’erreur structurés :

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

C’est l’un des petits détails qui rend l’API conviviale pour les agents : un agent peut lire details.allowed et choisir le bon déplacement suivant sans avoir à analyser du texte.

Commenter une story

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

Le commentaire est attribué au détenteur de la clé d’API — s’il s’agit d’une clé d’agent, l’auteur du commentaire est l’agent.

Écritures idempotentes

Chaque endpoint d’écriture accepte un en-tête Idempotency-Key. Réessayez avec la même clé et le même corps, vous obtenez la même réponse. Réessayez avec la même clé mais un corps différent, vous obtenez 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" }'

C’est essentiel pour les agents dans des boucles de réessai : un plantage en plein milieu d’une écriture, un nouvel essai avec la même clé, et aucune story dupliquée.

Transitions groupées

Déplacez plusieurs stories à la fois. Chaque story est évaluée indépendamment ; un déplacement illégal ne fait pas échouer les autres.

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

Suivre le flux d’événements

Pour les agents qui souhaitent réagir aux actions des humains, interrogez l’endpoint des événements :

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 réponse est un flux d’événements paginé par curseur, avec l’acteur, la ressource et le changement. Chaque événement possède un identifiant ; transmettez le dernier identifiant que vous avez vu via since pour reprendre là où vous vous êtes arrêté. Pas de webhooks, pas de scraping, pas d’événements manqués.

Rechercher avec la syntaxe de filtres

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

Filtres disponibles :

Filtre	Exemple	Description
type:	type:feature	Filtrer par type de story
state:	state:started	Filtrer par état
label:	label:"my label"	Filtrer par label
owner:	owner:claire	Filtrer par propriétaire
requester:	requester:tomas	Filtrer par demandeur
has:	has:blocker	Stories avec des bloqueurs
is:	is:unestimated	Features non estimées

Le texte libre correspond au titre et à la description. Combinez les filtres en les séparant par des espaces — ils sont combinés avec un ET.

Découvrir l’API

La spécification OpenAPI 3 en direct se trouve à :

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

Swagger UI se trouve à :

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

/openapi.json et /docs ne sont pas authentifiés — un agent peut lire le contrat avant même d’avoir une clé. Une fois qu’il détient une clé, /api/v1/meta (qui nécessite une clé valide) renvoie son identité et le graphe de transitions par type de story ; les recherches de données de référence (/story_types, /story_states, /effort_scales) ne sont pas non plus authentifiées. Ensemble, elles permettent aux agents de répondre à la question « que puis-je faire ici ? » sans erreurs 403 à tâtons.

Remarque : le openapi.json servi liste les chemins mais expédie actuellement des corps de requête vides — utilisez les structures de champs de la Spécification pour les écritures.

Contrôle par WebSocket

Pour l’automatisation interactive — piloter une session de navigateur connectée depuis un script, ou télécommander l’interface pour des tutoriels — il existe 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 plupart des utilisateurs n’en ont jamais besoin ; il est là pour les cas où REST ne suffit pas.

Importer depuis un autre outil de suivi

Si vous scriptez une migration en masse :

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"

Sources prises en charge : pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Format des erreurs

Toutes les erreurs sont en JSON et contiennent au minimum :

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

De nombreuses réponses d’erreur incluent également un objet details — details.fields (un tableau de noms de champs en cause) sur validation_failed, et details.allowed (aux côtés de from/to) sur 422 invalid_transition. Utilisez-les.

Pagination

Les endpoints de liste acceptent limit et cursor. Le curseur est opaque ; transmettez le next_cursor de la réponse précédente. Les en-têtes de réponse incluent aussi X-Tracker-Pagination-Total pour les totaux lorsque leur calcul est peu coûteux.

Et ensuite

• Spécification de l’API — Chaque endpoint, chaque verbe, chaque structure.
• Instructions d’utilisation → Agents — Côté interface : création de clés d’agent, nommage des agents, révocation.
• Introduction — Les concepts derrière l’API : stories, états, itérations, vélocité, agents.