API-Spezifikation

Die vollständige REST-Endpunktreferenz. Für Tutorials und Beispiele siehe den API-Leitfaden.

Alles, was ein Projektmitglied in der Web-Benutzeroberfläche tun kann, ist hier verfügbar — die SPA nutzt dieselbe API. Operationen, die die Owner-Rolle erfordern, sind mit (owner) markiert; alles andere benötigt nur die Projektmitgliedschaft (oder, für mit (viewer) markierte Lesevorgänge, jede Zugriffsebene).

Basis

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 liefert die identische API. Alle Anfragen und Antworten sind JSON, außer ein paar Datei-Upload-Endpunkten, die Multipart akzeptieren.

Authentifizierung

Jede authentifizierte Anfrage sendet einen API-Schlüssel über einen von:

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

Benutzerschlüssel beginnen mit ea_user_. Agenten-Schlüssel beginnen mit ea_agent_. Siehe API-Leitfaden → Zwei Arten von Schlüsseln.

Nicht authentifizierte Endpunkte: /openapi.json, /docs, die /auth/*-Endpunkte und die Referenzdaten-Lookups (/story_types, /story_states, /effort_scales, …). /meta ist authentifiziert — jeder gültige Schlüssel funktioniert, aber er ist nicht projektbezogen (auch ein projektgebundener Agenten-Schlüssel erreicht ihn).

Rollen

Drei Ebenen steuern projektbezogene Endpunkte:

Ebene	Wer passiert	Typische Operationen
viewer	viewer, member, owner	Lesevorgänge (Stories listen/abrufen, Suche, Analytics)
member	member, owner	alle Schreibvorgänge auf Arbeitselementen (Stories, Tasks, Kommentare, …)
owner	nur owner	Projekteinstellungen, Mitgliedschaftsverwaltung, Agenten-Schlüssel, Löschen, Import, Audit-Log

Ein Nicht-Mitglied erhält 404 unfound_resource (nicht 403) auf Projektpfaden, sodass Projekt-IDs nicht aufzählbar sind.

Selbstbeschreibende Endpunkte

Methode	Pfad	Beschreibung
GET	/openapi.json	Die Live-OpenAPI-3-Spezifikation. Nicht authentifiziert.
GET	/docs	Swagger UI. Nicht authentifiziert.
GET	/meta	Aufrufer-Identität (auth.kind/key_id/agent_id/project_id) + der Transition-Graph pro Story-Typ. Authentifiziert (jeder gültige Schlüssel; nicht projektbezogen). Rufen Sie dies zuerst auf.

Konto / Identität

Diese wirken auf den Aufrufer und benötigen nur einen gültigen Schlüssel (keine Projektrolle).

Methode	Pfad	Beschreibung
POST	/auth/register	Ein neues Konto registrieren
POST	/auth/login	Anmelden, gibt ein Sitzungs-Token zurück
POST	/auth/logout	Abmelden
POST	/auth/forgot-password	Eine Passwort-Zurücksetzungs-E-Mail anfordern
POST	/auth/reset-password	Ein Reset-Token verwenden, um ein neues Passwort zu setzen
GET	/auth/verify-email	Eine E-Mail-Adresse verifizieren
POST	/auth/accept-invite/lookup	Ein Einladungs-Token → E-Mail auflösen (nicht authentifiziert)
POST	/auth/accept-invite	Eine Projekteinladung annehmen (nach der Authentifizierung)
GET	/me	Aktuelles Benutzerprofil
PUT	/me	Profil aktualisieren
DELETE	/me	Konto löschen
PUT	/me/password	Passwort ändern
PUT	/me/settings	Einstellungen aktualisieren (Theme, Benachrichtigungspräferenzen)
POST	/me/avatar	Avatar hochladen (Multipart)
POST	/me/api-token/regenerate	Ihr API-Token rotieren — macht bestehende Sitzungen/Schlüssel ungültig
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Benutzer- (ea_user_) API-Schlüssel verwalten
GET	/me/activity	Ihre Aktivität über alle Projekte hinweg
GET	/me/data-export	DSGVO-Selbstexport Ihrer Daten
GET	/me/consent · POST /me/consent	Einwilligung lesen / aufzeichnen ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Ausstehende Clickwrap-Dokumente / Annahme aufzeichnen
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Kontakt + In-App-Feedback

Referenzdaten (nicht authentifiziert)

Seed-Lookups, die beim Erstellen/Schätzen von Stories verwendet werden. Stabile IDs.

Methode	Pfad	Beschreibung
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	verfügbare Schätzskalen
GET	/effort_scales/{scale_id}/values	die Punktewerte in einer Skala

Projekte

Methode	Pfad	Beschreibung
GET	/projects	Ihre Projekte auflisten
POST	/projects	Ein Projekt erstellen
GET	/projects/{id}	Projektdetails abrufen (viewer)
PUT	/projects/{id}	Projekteinstellungen aktualisieren (owner)
DELETE	/projects/{id}	Ein Projekt löschen (owner)
GET	/projects/{id}/audit-log	Projekt-Aktivitätsstream (owner)
GET	/projects/{id}/events	Cursor-paginierter Event-Stream (viewer) — siehe Events

Mitglieder und Agenten-Schlüssel

Methode	Pfad	Beschreibung
GET	/projects/{id}/memberships	Mitglieder auflisten (viewer)
POST	/projects/{id}/memberships	Ein Mitglied per E-Mail einladen (owner)
PUT	/projects/{id}/memberships/{mid}	Rolle aktualisieren (owner)
DELETE	/projects/{id}/memberships/{mid}	Ein Mitglied entfernen (owner)
GET / POST	/projects/{id}/agent_keys	Agenten-Schlüssel auflisten / ausstellen (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Einen Agenten-Schlüssel widerrufen (owner)

Stories

Alle Schreibvorgänge auf Stories benötigen die member-Rolle.

Methode	Pfad	Beschreibung
GET	/projects/{id}/stories	Stories auflisten (paginiert, filterbar) (viewer)
POST	/projects/{id}/stories	Eine Story erstellen
GET	/projects/{id}/stories/{sid}	Eine Story abrufen (viewer)
PUT	/projects/{id}/stories/{sid}	Eine Story aktualisieren
DELETE	/projects/{id}/stories/{sid}	Eine Story löschen
POST	/projects/{id}/stories/{sid}/transitions	Zustand mit Validierung ändern
POST	/projects/{id}/stories/bulk_transition	Viele Stories (1–100) auf einmal wechseln
POST	/projects/{id}/stories/bulk-delete	Viele Stories löschen
POST	/projects/{id}/stories/bulk-duplicate	Viele Stories duplizieren
POST	/projects/{id}/stories/{sid}/duplicate	Eine Story duplizieren

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels akzeptiert ["auth"] oder [{ "name": "auth" }]; unbekannte Labels werden erstellt. Voreinstellungen: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): dieselben Felder, alle optional, plus "position" (float) und "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. Das Feld ist to. Gibt { story_id, state } zurück. Unzulässige Bewegung → 422 invalid_transition mit details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Jede Story wird unabhängig beurteilt; gibt { results: [ { id, status: "ok" } | { id, status: "failed", error } ] } zurück.

Story-Unterressourcen

Alle member. List/GET ist bei den meisten (viewer).

Methode	Pfad	Body / Hinweise
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) } oder { 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? } — beides weglassen, um den Aufrufer hinzuzufügen
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}	Multipart-Upload (≤ 2 GB pro Stück); Liste ist (viewer)

Labels

member für Schreibvorgänge, (viewer) für Lesevorgänge.

Methode	Pfad	Beschreibung
GET / POST	/projects/{id}/labels	Ein Label auflisten / erstellen
PUT / DELETE	/projects/{id}/labels/{lid}	Ein Label aktualisieren / löschen
POST	/projects/{id}/labels/{lid}/archive	Ein Label archivieren (sanft ausblenden)

Iterationen

Methode	Pfad	Beschreibung
GET	/projects/{id}/iterations	Iterationen auflisten (member)
POST	/projects/{id}/iterations	Eine manuelle Iteration erstellen (owner)
DELETE	/projects/{id}/iterations/{itid}	Eine Iteration löschen (owner)

Suche, Analytics, Metriken, Präferenzen

Methode	Pfad	Beschreibung
GET	/projects/{id}/search?query=…	Suche mit Filtersyntax (viewer) — siehe Leitfaden
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analytics (viewer). Iterations-Drilldown nimmt ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metriken (viewer)
GET / PUT	/projects/{id}/preferences	Ihre Board-Präferenzen für dieses Projekt (member)

Events

Methode	Pfad	Beschreibung
GET	/projects/{id}/events	Cursor-paginierter Event-Stream (viewer)

Query-Parameter: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Die Antwort enthält next_cursor. Übergeben Sie die letzte event_id, die Sie gesehen haben, als since, um fortzufahren.

Import (owner)

Methode	Pfad	Beschreibung
POST	/projects/{id}/import (+ /json)	Multipart-Upload. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

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

Für interaktive UI-Fernsteuerung ({ "action": "get_state", "id": "req-1" }). Kein Datenkanal — alle Lese-/Schreibvorgänge laufen über REST. Nur Einzelinstanz; nicht über Replikate verteilt.

Idempotenz

Schreib-Endpunkte (POST, PUT, DELETE) akzeptieren einen Idempotency-Key-Header. Derselbe Schlüssel + derselbe Body spielt die zwischengespeicherte Antwort erneut ab (24-Stunden-Fenster); derselbe Schlüssel + ein anderer Body gibt 409 idempotency_conflict zurück. Nicht angewendet auf GET/HEAD/OPTIONS, /auth/* oder /attachments-Pfade. 5xx-Antworten werden nie zwischengespeichert — ein Retry erreicht den Handler.

Paginierung

List-Endpunkte akzeptieren cursor=<opaque> und limit=<n≤200>. Wenn gesetzt, ist die Antwort { "items": [...], "next_cursor": "<str|null>" }; übergeben Sie next_cursor zurück, um zu blättern. Einige Listen geben auch einen X-Tracker-Pagination-Total-Header zurück.

Feldprojektion

List-Endpunkte akzeptieren fields= (kommagetrennt), um nur bestimmte Felder zurückzugeben. story_id ist immer enthalten; ein unbekannter Feldname gibt 400 validation_failed mit den beanstandeten Namen in details.fields zurück.

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

Fehlerformat

Jeder JSON-Fehler hat code und error; einige fügen details hinzu:

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

Status	code	Wann
400	invalid_parameter	fehlerhafte Eingabe; Nachricht in error, kein details (die meiste Validierung: leer/Länge/Null-Byte/E-Mail)
400	validation_failed	strukturierter Eingabefehler; details.fields ist ein Array von beanstandeten Feldnamen
401	unauthenticated	fehlendes/ungültiges Token
403	unauthorized_operation	authentifiziert, aber unzureichende Rolle
404	unfound_resource	nicht gefunden — wird auch an Nicht-Mitglieder zurückgegeben
409	conflict	Ressourcenkonflikt (z. B. Duplikat)
409	idempotency_conflict	Idempotency-Key mit einem anderen Body wiederverwendet
422	invalid_transition	unzulässige Zustandsbewegung; details trägt { from, to, allowed }
500	internal_error	Serverfehler — generische Nachricht; sicher zu wiederholen

details.fields ist ein JSON-Array von Feldnamen (z. B. ["to"]), manchmal mit zusätzlichen Schlüsseln wie max. Es gibt keine Feld→Nachricht-Zuordnung.

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

Ratenbegrenzungen

Pro Schlüssel (pro IP für nicht authentifizierte Endpunkte), GCRA-Token-Bucket:

• Auth — /auth/*: 0,5 req/s, Burst 20.
• Public — /contact, /feedback: 0,2 req/s, Burst 10.
• Sensitive — Passwort-Zurücksetzung: ~0,002 req/s, Burst 5.

Eine überschrittene Begrenzung gibt 429 Too Many Requests mit einem Retry-After-Header und einem Klartext-Body zurück (nicht der JSON-Fehlerumschlag).