API-Leitfaden

Die East Agile Tracker API ist für Agenten ebenso wie für Menschen konzipiert. Alles, was Sie in der Benutzeroberfläche tun können, können Sie über die API tun — und ein paar Dinge, die die Benutzeroberfläche nicht offenlegt, sind ebenfalls dabei.

Dieser Leitfaden bringt Sie in unter zehn Minuten von null auf „Ihr Backlog skripten”. Für die vollständige Endpunktreferenz siehe API-Spezifikation.

Zwei Arten von Schlüsseln

Sie authentifizieren sich mit einem API-Schlüssel im X-TrackerToken-Header. Es gibt zwei Arten:

• Benutzerschlüssel (ea_user_…) — Handeln als Sie. Erstellen Sie sie in Account-Einstellungen → API-Schlüssel. Verwenden Sie diese für persönliche Skripte, CLI-Tools, Integrationen.
• Agenten-Schlüssel (ea_agent_…) — Handeln als benannter Agent in einem Projekt. Erstellen Sie sie als Projekt-Owner in Project Settings → Agents. Verwenden Sie diese für KI-Agenten — Claude Code, Codex, Ihren eigenen — die als benannte Teammitglieder am Projekt teilnehmen sollen.

Die Unterschiede:

	Benutzerschlüssel	Agenten-Schlüssel
Geltungsbereich	Alle Ihre Projekte	Ein bestimmtes Projekt
Identität im Audit-Log	Ihr Name	Der Name des Agenten
Rolle	Ihre Rolle in jedem Projekt	Bei Schlüsselerstellung festgelegt (viewer oder member)
Widerruf	Schlüssel widerrufen; Zugang über andere Schlüssel/Sitzungen bleibt	Schlüssel widerrufen; der Agent verliert sofort den Zugriff
Am besten für	Persönliche Automatisierung, Skripte	KI-Agenten, die sich in der Historie von Ihnen unterscheiden lassen sollen

Authorization: Bearer … funktioniert ebenfalls, wenn Sie diesen Header-Stil bevorzugen.

Hello, API

Rufen Sie Ihre Projekte ab:

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

Oder für einen Agenten-Schlüssel listen Sie das Projekt auf, auf das er beschränkt ist:

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

Die API ist JSON, REST-artig, versioniert unter /api/v1/. Dieselben Formen für Menschen und Agenten.

Ein Projekt erstellen

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

Die Antwort enthält die project_id und alle Voreinstellungen, die der Server angewendet hat (Schätzskala, Done-State usw.).

Eine Story erstellen

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

Eine Story durch den Lebenszyklus bewegen

Der Transition-Endpunkt validiert die angeforderte Bewegung und gibt bei einem Fehler die erlaubten nächsten Zustände zurück:

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

Das Feld ist to (nicht to_state). Wenn die Bewegung unzulässig ist — sagen wir, Sie haben versucht, von unstarted direkt zu accepted zu springen — ist die Antwort 422 invalid_transition mit strukturierten Fehlerdetails:

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

Das ist eines der kleinen Dinge, die die API agentenfreundlich machen: Ein Agent kann details.allowed lesen und die richtige nächste Bewegung wählen, ohne Prosa zu scrapen.

Eine Story kommentieren

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

Der Kommentar wird demjenigen zugeschrieben, dem der API-Schlüssel gehört — wenn es ein Agenten-Schlüssel ist, ist der Autor des Kommentars der Agent.

Idempotente Schreibvorgänge

Jeder Schreib-Endpunkt akzeptiert einen Idempotency-Key-Header. Wiederholen Sie denselben Schlüssel mit demselben Body, erhalten Sie dieselbe Antwort zurück. Wiederholen Sie denselben Schlüssel mit einem anderen Body, erhalten Sie einen 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" }'

Das ist kritisch für Agenten in Retry-Schleifen — mitten im Schreibvorgang abstürzen, mit demselben Schlüssel erneut versuchen, keine doppelten Stories.

Massenübergänge

Bewegen Sie viele Stories auf einmal. Jede Story wird unabhängig beurteilt; eine unzulässige Bewegung lässt die anderen nicht fehlschlagen.

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

Dem Event-Stream folgen

Für Agenten, die auf das reagieren möchten, was Menschen tun, pollen Sie den Events-Endpunkt:

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"

Die Antwort ist ein cursor-paginierter Stream von Events mit dem Akteur, der Ressource und der Änderung. Jedes Event hat eine ID; übergeben Sie die letzte ID, die Sie gesehen haben, als since, um dort fortzufahren, wo Sie aufgehört haben. Keine Webhooks, kein Scraping, keine verpassten Events.

Mit der Filtersyntax suchen

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

Verfügbare Filter:

Filter	Beispiel	Beschreibung
type:	type:feature	Nach Story-Typ filtern
state:	state:started	Nach Zustand filtern
label:	label:"my label"	Nach Label filtern
owner:	owner:claire	Nach Owner filtern
requester:	requester:tomas	Nach Requestor filtern
has:	has:blocker	Stories mit Blockern
is:	is:unestimated	Ungeschätzte Features

Freitext stimmt mit Titel und Beschreibung überein. Kombinieren Sie Filter, indem Sie sie durch Leerzeichen trennen — sie werden UND-verknüpft.

Die API entdecken

Die Live-OpenAPI-3-Spezifikation befindet sich unter:

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

Swagger UI befindet sich unter:

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

/openapi.json und /docs sind nicht authentifiziert — ein Agent kann den Vertrag lesen, bevor er einen Schlüssel hat. Sobald er einen Schlüssel besitzt, gibt /api/v1/meta (was einen gültigen Schlüssel erfordert) seine Identität und den Transition-Graphen pro Story-Typ zurück; die Referenzdaten-Lookups (/story_types, /story_states, /effort_scales) sind ebenfalls nicht authentifiziert. Zusammen lassen sie Agenten „Was kann ich hier tun?” beantworten, ohne Trial-and-Error-403s.

Hinweis: Die ausgelieferte openapi.json listet Pfade auf, liefert aber derzeit leere Request-Bodies — verwenden Sie die Feldformen in der Spezifikation für Schreibvorgänge.

WebSocket-Steuerung

Für interaktive Automatisierung — das Steuern einer angemeldeten Browser-Sitzung aus einem Skript oder das Fernsteuern der Benutzeroberfläche für Tutorials — gibt es einen WebSocket-Kanal:

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

Die meisten Benutzer brauchen dies nie; es ist für die Fälle da, in denen REST nicht ausreicht.

Aus einem anderen Tracker importieren

Wenn Sie eine Massenmigration skripten:

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"

Unterstützte Quellen: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Fehlerformat

Alle Fehler sind JSON mit mindestens:

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

Viele Fehlerantworten enthalten auch ein details-Objekt — details.fields (ein Array von beanstandeten Feldnamen) bei validation_failed und details.allowed (neben from/to) bei 422 invalid_transition. Nutzen Sie sie.

Paginierung

List-Endpunkte akzeptieren limit und cursor. Der Cursor ist opak; übergeben Sie das next_cursor aus der vorherigen Antwort. Die Antwort-Header enthalten zudem X-Tracker-Pagination-Total für Gesamtzahlen, wo die Berechnung günstig ist.

Wie es weitergeht

• API-Spezifikation — Jeder Endpunkt, jedes Verb, jede Form.
• Bedienungsanleitung → Agenten — UI-seitig: Agenten-Schlüssel ausstellen, Agenten benennen, widerrufen.
• Einführung — Konzepte hinter der API: Stories, Zustände, Iterationen, Velocity, Agenten.