Spécification de l'API

La référence complète des endpoints REST. Pour les tutoriels et les exemples, voir le Guide de l’API.

Tout ce qu’un membre de projet peut faire dans l’interface web est disponible ici — la SPA consomme cette même API. Les opérations nécessitant le rôle propriétaire sont marquées (owner) ; tout le reste ne requiert que l’appartenance au projet (ou, pour les lectures marquées (viewer), n’importe quel niveau d’accès).

Base

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 sert l’API identique. Toutes les requêtes et réponses sont en JSON, à l’exception de quelques endpoints d’envoi de fichiers qui acceptent le multipart.

Authentification

Chaque requête authentifiée envoie une clé d’API via l’un des moyens suivants :

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Les clés utilisateur commencent par ea_user_. Les clés d’agent commencent par ea_agent_. Voir Guide de l’API → Deux types de clés.

Endpoints non authentifiés : /openapi.json, /docs, les endpoints /auth/*, et les recherches de données de référence (/story_types, /story_states, /effort_scales, …). /meta est authentifié — n’importe quelle clé valide fonctionne, mais il n’est pas restreint à un projet (une clé d’agent liée à un projet y accède également).

Rôles

Trois niveaux contrôlent l’accès aux endpoints restreints à un projet :

Niveau	Qui passe	Opérations types
viewer	viewer, member, owner	lectures (lister/obtenir des stories, recherche, analyses)
member	member, owner	toutes les écritures sur les éléments de travail (stories, tâches, commentaires, …)
owner	owner uniquement	paramètres du projet, gestion des membres, clés d’agent, suppression, import, journal d’audit

Un non-membre reçoit 404 unfound_resource (et non 403) sur les chemins de projet, de sorte que les identifiants de projet ne sont pas énumérables.

Endpoints auto-descriptifs

Méthode	Chemin	Description
GET	/openapi.json	La spécification OpenAPI 3 en direct. Non authentifié.
GET	/docs	Swagger UI. Non authentifié.
GET	/meta	Identité de l’appelant (auth.kind/key_id/agent_id/project_id) + le graphe de transitions par type de story. Authentifié (n’importe quelle clé valide ; non restreint à un projet). À appeler en premier.

Compte / identité

Ces opérations agissent sur l’appelant et ne nécessitent qu’une clé valide (aucun rôle de projet).

Méthode	Chemin	Description
POST	/auth/register	Enregistrer un nouveau compte
POST	/auth/login	Se connecter, renvoie un jeton de session
POST	/auth/logout	Se déconnecter
POST	/auth/forgot-password	Demander un e-mail de réinitialisation du mot de passe
POST	/auth/reset-password	Utiliser un jeton de réinitialisation pour définir un nouveau mot de passe
GET	/auth/verify-email	Vérifier une adresse e-mail
POST	/auth/accept-invite/lookup	Résoudre un jeton d’invitation → e-mail (non authentifié)
POST	/auth/accept-invite	Accepter une invitation à un projet (après authentification)
GET	/me	Profil de l’utilisateur actuel
PUT	/me	Mettre à jour le profil
DELETE	/me	Supprimer le compte
PUT	/me/password	Changer le mot de passe
PUT	/me/settings	Mettre à jour les paramètres (thème, préférences de notification)
POST	/me/avatar	Téléverser un avatar (multipart)
POST	/me/api-token/regenerate	Régénérer votre jeton d’API — invalide les sessions/clés existantes
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Gérer les clés d’API utilisateur (ea_user_)
GET	/me/activity	Votre activité sur tous les projets
GET	/me/data-export	Auto-export RGPD de vos données
GET	/me/consent · POST /me/consent	Lire / enregistrer le consentement ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Documents clickwrap en attente / enregistrer l’acceptation
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Contact + retours dans l’application

Données de référence (non authentifiées)

Recherches sur les données de référence utilisées lors de la création/estimation des stories. Identifiants stables.

Méthode	Chemin	Description
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	échelles d’estimation disponibles
GET	/effort_scales/{scale_id}/values	les valeurs de points d’une échelle

Projets

Méthode	Chemin	Description
GET	/projects	Lister vos projets
POST	/projects	Créer un projet
GET	/projects/{id}	Obtenir les détails du projet (viewer)
PUT	/projects/{id}	Mettre à jour les paramètres du projet (owner)
DELETE	/projects/{id}	Supprimer un projet (owner)
GET	/projects/{id}/audit-log	Flux d’activité du projet (owner)
GET	/projects/{id}/events	Flux d’événements paginé par curseur (viewer) — voir Événements

Membres et clés d’agent

Méthode	Chemin	Description
GET	/projects/{id}/memberships	Lister les membres (viewer)
POST	/projects/{id}/memberships	Inviter un membre par e-mail (owner)
PUT	/projects/{id}/memberships/{mid}	Mettre à jour le rôle (owner)
DELETE	/projects/{id}/memberships/{mid}	Retirer un membre (owner)
GET / POST	/projects/{id}/agent_keys	Lister / créer des clés d’agent (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Révoquer une clé d’agent (owner)

Stories

Toutes les écritures sur les stories nécessitent le rôle member.

Méthode	Chemin	Description
GET	/projects/{id}/stories	Lister les stories (paginées, filtrables) (viewer)
POST	/projects/{id}/stories	Créer une story
GET	/projects/{id}/stories/{sid}	Obtenir une story (viewer)
PUT	/projects/{id}/stories/{sid}	Mettre à jour une story
DELETE	/projects/{id}/stories/{sid}	Supprimer une story
POST	/projects/{id}/stories/{sid}/transitions	Changer d’état avec validation
POST	/projects/{id}/stories/bulk_transition	Faire transiter plusieurs stories (1–100) à la fois
POST	/projects/{id}/stories/bulk-delete	Supprimer plusieurs stories
POST	/projects/{id}/stories/bulk-duplicate	Dupliquer plusieurs stories
POST	/projects/{id}/stories/{sid}/duplicate	Dupliquer une story

Création (POST …/stories) : { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels accepte ["auth"] ou [{ "name": "auth" }] ; les labels inconnus sont créés. Valeurs par défaut : story_type=feature, current_state=unstarted.

Mise à jour (PUT …/stories/{sid}) : mêmes champs, tous optionnels, plus "position" (float) et "force_state_change" (bool).

Transition (POST …/transitions) : { "to": "<state>", "reason"? }. Le champ est to. Renvoie { story_id, state }. Déplacement illégal → 422 invalid_transition avec details: { from, to, allowed }.

Transition groupée (POST …/bulk_transition) : { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Chaque story est évaluée indépendamment ; renvoie { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Sous-ressources des stories

Toutes en member. La liste/GET sur la plupart est en (viewer).

Méthode	Chemin	Corps / notes
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (or task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (or comment_text) } ou { comment_emoji }
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · DELETE …/links/{lid}	{ url, link_type?, title? }
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	{ reviewer_id? / reviewer_agent_id?, status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — omettez les deux pour ajouter l’appelant
GET / POST	/projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid}	{ member_id? / agent_id? }
GET / POST	/projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	envoi multipart (≤ 2 Go chacun) ; la liste est en (viewer)

Labels

member pour les écritures, (viewer) pour les lectures.

Méthode	Chemin	Description
GET / POST	/projects/{id}/labels	Lister / créer un label
PUT / DELETE	/projects/{id}/labels/{lid}	Mettre à jour / supprimer un label
POST	/projects/{id}/labels/{lid}/archive	Archiver (masquer en douceur) un label

Itérations

Méthode	Chemin	Description
GET	/projects/{id}/iterations	Lister les itérations (member)
POST	/projects/{id}/iterations	Créer une itération manuelle (owner)
DELETE	/projects/{id}/iterations/{itid}	Supprimer une itération (owner)

Recherche, analyses, métriques, préférences

Méthode	Chemin	Description
GET	/projects/{id}/search?query=…	Recherche par syntaxe de filtres (viewer) — voir le Guide
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analyses (viewer). Le détail par itération prend ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Métriques (viewer)
GET / PUT	/projects/{id}/preferences	Vos préférences de tableau pour ce projet (member)

Événements

Méthode	Chemin	Description
GET	/projects/{id}/events	Flux d’événements paginé par curseur (viewer)

Paramètres de requête : since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. La réponse inclut next_cursor. Transmettez le dernier event_id que vous avez vu via since pour reprendre.

Import (owner)

Méthode	Chemin	Description
POST	/projects/{id}/import (+ /json)	Envoi multipart. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

Pour la télécommande interactive de l’interface ({ "action": "get_state", "id": "req-1" }). Ce n’est pas un canal de données — toutes les lectures/écritures passent par REST. Mono-instance uniquement ; non distribué entre les réplicas.

Idempotence

Les endpoints d’écriture (POST, PUT, DELETE) acceptent un en-tête Idempotency-Key. La même clé + le même corps rejoue la réponse mise en cache (fenêtre de 24 heures) ; la même clé + un corps différent renvoie 409 idempotency_conflict. Non appliqué aux requêtes GET/HEAD/OPTIONS, /auth/*, ni aux chemins /attachments. Les réponses 5xx ne sont jamais mises en cache — un nouvel essai atteint le gestionnaire.

Pagination

Les endpoints de liste acceptent cursor=<opaque> et limit=<n≤200>. Lorsqu’ils sont définis, la réponse est { "items": [...], "next_cursor": "<str|null>" } ; renvoyez next_cursor pour paginer. Certaines listes renvoient aussi un en-tête X-Tracker-Pagination-Total.

Projection de champs

Les endpoints de liste acceptent fields= (séparés par des virgules) pour ne renvoyer que des champs spécifiques. story_id est toujours inclus ; un nom de champ inconnu renvoie 400 validation_failed avec les noms en cause dans details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Format des erreurs

Chaque erreur JSON possède code et error ; certaines ajoutent details :

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

Statut	code	Quand
400	invalid_parameter	entrée incorrecte ; message dans error, pas de details (la plupart des validations : vide/longueur/octet null/e-mail)
400	validation_failed	erreur d’entrée structurée ; details.fields est un tableau de noms de champs en cause
401	unauthenticated	jeton manquant/invalide
403	unauthorized_operation	authentifié mais rôle insuffisant
404	unfound_resource	introuvable — également renvoyé aux non-membres
409	conflict	conflit de ressource (par ex. doublon)
409	idempotency_conflict	Idempotency-Key réutilisée avec un corps différent
422	invalid_transition	déplacement d’état illégal ; details contient { from, to, allowed }
500	internal_error	défaillance serveur — message générique ; peut être réessayé sans risque

details.fields est un tableau JSON de noms de champs (par ex. ["to"]), parfois accompagné de clés supplémentaires comme max. Il n’y a pas de correspondance champ→message.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Limites de débit

Par clé (par IP pour les endpoints non authentifiés), seau à jetons GCRA :

• Auth — /auth/* : 0,5 req/s, rafale 20.
• Public — /contact, /feedback : 0,2 req/s, rafale 10.
• Sensible — réinitialisation du mot de passe : ~0,002 req/s, rafale 5.

Une limite dépassée renvoie 429 Too Many Requests avec un en-tête Retry-After et un corps en texte brut (et non l’enveloppe d’erreur JSON).