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.

Trois types d’identifiants

Vous vous authentifiez avec une clé dans l’en-tête X-TrackerToken. Il existe deux types de clés que vous créez vous-même, et un troisième qu’un client MCP obtient pour vous :

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 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.
Jetons MCP (ea_mcp_…) — Des jetons d’accès OAuth 2.1 délivrés à un client MCP (Claude, un IDE) après que vous l’avez approuvé sur la page de consentement. Ils agissent en tant que vous, et vous pouvez les révoquer dans Paramètres du compte → Applications connectées.

La boîte de dialogue unique après la création d'une clé API personnelle dans les paramètres du compte, la clé étant masquée

Le formulaire de création de clé de l'onglet Agent avec un nom et le rôle member choisi, sous les instructions de configuration

Les différences entre les deux que vous créez vous-même :

	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, member ou manager — jamais au-dessus du rôle du membre qui la crée)
Révocation	Révoquez une clé ; vous conservez l’accès via d’autres clés/sessions	Révoquez ou faites tourner 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"]
  }'

estimate est le libellé de la valeur d’échelle, sous forme de chaîne — "3", ou "13" sur l’échelle Fibonacci — car il doit correspondre à un point de l’échelle du projet. Un nombre JSON est rejeté.

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.

rejected est terminal pour l’endpoint de transition. Pour remettre au travail une story rejetée, faites POST …/stories/{sid}/restart ; POST …/stories/{sid}/reject est la forme verbale du rejet d’une story livrée.

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.added" \
  -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. Le flux exige le rôle member — un viewer reçoit 403.

Recherche

GET /projects/{id}/search?q=<query> lance une puissante recherche plein texte + structurée sur les stories du projet. Le langage de requête est calqué sur les qualificateurs de recherche d’issues de GitHub — la syntaxe que vous (ou un agent IA) connaissez déjà depuis GitHub se transpose donc en grande partie.

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'

La réponse est une enveloppe JSON, les stories étant classées par pertinence :

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

total est le nombre total de correspondances, pas la taille de la page. Paginez avec limit (50 par défaut, max 1000) et offset ; triez avec sort=relevance (par défaut), created, created_asc, updated ou state.

Grammaire

Le texte libre correspond au titre, à la référence et à la description d’une story (plein texte, avec racinisation et classement). Encadrez une phrase exacte par des "guillemets".
Les qualificateurs s’écrivent field:value. Séparez les alternatives par des virgules (OU au sein d’un champ) : type:bug,chore. Séparez les qualificateurs par des espaces (ET entre eux).
Niez n’importe quel terme ou qualificateur avec un - en tête : -label:wontfix.
Les plages pour les dates et les points : inclusive a..b, ou ouverte >x / <x.

Qualificateurs

Qualificateur	Exemple	Correspond à
`type:`	`type:bug,chore`	le ou les types de story
`state:`	`state:started,finished`	le ou les états du flux de travail
`label:`	`label:"my label"`	un label
`epic:`	`epic:"Checkout"`	les stories d’un epic
`priority:`	`priority:p1`	la priorité
`points:`	`points:3` · `points:1..5` · `points:>3`	une valeur d’estimation ou une plage
`iteration:`	`iteration:42`	l’id d’une itération
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	une date ou une plage (au jour près) ; `release:` est la date de release de la story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	une personne par nom ou e-mail — membres et agents, `mention:` compris ; `@me`, c’est vous
`has:blocker`	`has:blocker`	possède un bloqueur ouvert
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	un drapeau

mywork: est un alias de owner: — mywork:me équivaut à owner:@me. L’ancien qualificateur scheduled: est retiré et silencieusement ignoré ; utilisez release:.

Le OU par virgules (type:bug,chore) s’applique aux qualificateurs de facettes ; les qualificateurs de personnes (owner: requester: follower: reviewer: commenter: mention:) n’acceptent qu’une seule valeur.

Exemples

payment crash                              texte libre « payment » ET « crash »
"exact phrase"                             une phrase exacte
type:bug,chore state:started               bugs ou chores démarrés
owner:@me -label:wontfix                   les miennes, hors label wontfix
points:3..8 created:2026-05-01..2026-06-01 estimées 3-8, créées en mai
follower:tomas has:blocker                 tomas la suit et elle est bloquée
is:backlog updated:>2026-06-01             éléments du backlog touchés depuis le 1er juin

La même chaîne de requête alimente le champ de recherche du tableau (qui ouvre une colonne de résultats en direct) et cette API — une seule grammaire pour les humains comme pour les agents. La recherche dans le contenu des commentaires, des tâches et des bloqueurs est à la feuille de route ; aujourd’hui le texte libre couvre le titre, la référence et la description de la story elle-même.

Découvrir l’API

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

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

Swagger UI se trouve à :

https://api.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, /priority_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.

Le openapi.json servi porte les schémas de corps de requête des endpoints d’écriture, y compris le maxLength de chaque champ, de sorte qu’un client peut valider avant d’envoyer. La Spécification résume les mêmes structures.

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

Le token est le JWT de la session du navigateur, et non une clé d’API — une clé ea_user_* ou ea_agent_* est refusée avant la bascule de protocole. 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 de fichiers prises en charge : pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (le propre export d’East Agile Tracker — le format d’aller-retour). L’endpoint multipart s’exécute de façon synchrone et répond avec les compteurs de résultats.

GitHub importe depuis l’API plutôt que depuis un fichier, via l’endpoint JSON — pas de file, juste les coordonnées du dépôt :

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

L’endpoint JSON est asynchrone : il répond 202 avec { "import_id", "status" } et vous interrogez GET /projects/{id}/imports/{import_id} jusqu’à ce que le job atteigne done ou failed. Un seul import s’exécute par projet à la fois — un second appel pendant qu’un autre est en cours donne 409 import_already_running. Toute la boucle, avec les champs de progression du job, est décrite dans Alimenter un projet depuis un dépôt GitHub.

Le token est facultatif sur le fil, mais la récupération elle-même s’authentifie toujours — elle passe par l’API GraphQL de GitHub, qui n’a pas de palier anonyme. Omettez token et le serveur substitue son jeton de plateforme : dépôts publics uniquement, partagé par tous les appelants, et refusé avec import_github_shared_quota_low lorsque son budget GraphQL descend sous 500 points. Un dépôt privé, ou un déploiement qui n’a configuré aucun jeton de plateforme (import_github_no_token), exige le vôtre. Quel que soit le jeton utilisé, il ne sert qu’aux appels GitHub en amont et n’est jamais stocké ni renvoyé. Le détail complet, y compris le plafond REST non authentifié de 60 requêtes de GitHub, se trouve dans Alimenter un projet depuis un dépôt GitHub.

Aperçu à blanc (dry-run). Ajoutez "dry_run": true (JSON) ou -F "dry_run=true" (multipart) à n’importe quelle source. L’import analyse, résout et dédoublonne exactement comme une exécution réelle, produit les mêmes compteurs de résultats (imported, skipped, errors, unmatched), puis annule tout — rien n’est écrit. Sur l’endpoint JSON, les compteurs arrivent sur le job interrogé, essai à blanc ou non.

Limites. Un corps de téléversement est plafonné à 10 MiB, et un import unique à 5 000 stories ; dépasser l’une ou l’autre donne un 400 sans rien écrire. Réimporter un fichier est sans risque — les lignes déjà importées (identifiées par id source) sont ignorées, pas dupliquées.

Exporter un projet

N’importe quel rôle du projet peut lister les formats ; en télécharger un est réservé aux owners :

# Les formats d'export enregistrés : { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Télécharger un format (eat est le CSV d'aller-retour à fidélité complète)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Ids des formats d’échange : eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, plus les formats document pdf et docx. Toutes les pièces jointes sont téléchargeables dans un seul zip depuis GET /projects/{id}/export/attachments.

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. Un 429 rate_limited porte un en-tête Retry-After dans la même enveloppe JSON.

Pagination

Les endpoints de liste acceptent limit et cursor. Le curseur est opaque ; transmettez le next_cursor de la réponse précédente. Le plafond de limit dépend de l’endpoint — 200 sur les stories, les commentaires et les projets, 500 sur les événements, 1000 sur la recherche et le journal d’audit. Une liste simple (sans curseur) qui a dû tronquer sa réponse le signale dans des en-têtes : X-Tracker-Pagination-Truncated, -Limit, -Offset et -Next-Offset, que vous renvoyez comme offset= pour la page suivante. Il n’existe pas d’en-tête de nombre total.

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.