API-Übersicht

Vollständige Anleitung zur CodeCourier REST API mit 171 Endpunkten für Projekte, Workflows, Personas, Runs, Issues, Kontexte, Assets, Sprint-Chains, wiederkehrende Aufgaben, Antwortsitzungen, Learnings, Sandboxes, Webhooks, Benachrichtigungen, Analytics und mehr.

10 Min. Lesezeit

apioverviewrest

Die CodeCourier REST API bietet vollständigen programmatischen Zugriff auf jede Funktion des Web-Dashboards. Mit 171 Endpunkten verteilt auf 26 Ressourcenkategorien kann ein LLM oder ein Automatisierungsskript alles tun, was auch ein Mensch tun kann -- Projekte anlegen, Workflows konfigurieren, KI-Coding-Runs starten, Learnings verwalten, Kontexte und Assets konfigurieren, wiederkehrende Aufgaben planen und mehr. Alle Endpunkte werden über projektbezogene API-Schlüssel authentifiziert und liefern konsistente JSON-Antworten.

Basis-URL

Alle REST-API-Endpunkte werden über die HTTP-Actions-URL Ihres Convex-Deployments unter dem Präfix /api/v1/ bereitgestellt:

https://<your-deployment>.convex.site/api/v1/

Wichtig: Die Basis-URL endet auf .convex.site -- NICHT .convex.cloud. Die Domain .convex.cloud ist die intern verwendete Convex-Daten-WebSocket-URL. Die Domain .convex.site ist der HTTP-Actions-Endpunkt, der die REST API bereitstellt. Die Verwendung der falschen Domain führt zu Verbindungsfehlern.

Ihren Deployment-Namen finden Sie im Convex-Dashboard. Er sieht typischerweise so aus: happy-animal-123, was zu einer Basis-URL von https://happy-animal-123.convex.site/api/v1/ führt.

Authentifizierung

Jede Anfrage erfordert einen Projekt-API-Schlüssel, der als Bearer Token im Authorization-Header übergeben wird. Schlüssel werden über das Dashboard oder über die API selbst erzeugt. Siehe die Seite Authentifizierung für alle Details zum Erstellen und Verwalten von Schlüsseln.

curl -H "Authorization: Bearer cc_live_..." \
  https://<your-deployment>.convex.site/api/v1/project

Wichtig: Der Header lautet Authorization: Bearer <key> -- NICHT x-api-key, NICHT X-API-Key. API-Schlüssel beginnen mit cc_live_ (Produktion) oder cc_test_ (Testumgebungen).

Antwortformat

Alle erfolgreichen Antworten liefern:

{ "data": <result> }

Alle Fehlerantworten liefern:

{ "error": "Human-readable error message" }

Standard-HTTP-Statuscodes:

200 -- Erfolg
201 -- Erstellt (für Action-Endpunkte wie start)
400 -- Ungültige Anfrage (fehlende Felder, ungültiges JSON)
403 -- Verboten (ungültiger oder widerrufener API-Schlüssel)
404 -- Ressource nicht gefunden
500 -- Interner Serverfehler

Ressourcen-IDs: `id` vs. `_id`

Jede von der REST API zurückgegebene Ressource stellt ihren kanonischen Bezeichner unter zwei Feldnamen bereit: id (REST-Konvention) und _id (interner Convex-Alias, zur Abwärtskompatibilität beibehalten). Beide enthalten denselben intransparenten String und können beliebig austauschbar an jeden Endpunkt übergeben werden, der eine ID akzeptiert.

{
  "data": {
    "id":  "k57a8...",   // ← preferred in new code
    "_id": "k57a8...",   // ← retained for back-compat through 2026-10-24
    "name": "..."
  }
}

Neue Integrationen sollten id auslesen. Das Feld _id bleibt in jeder Projektion bis zum Sunset des v1-Envelope am 2026-10-24 erhalten; danach kann es ohne weitere Vorankündigung aus REST-Antworten entfernt werden. Die internen Convex-Queries sind davon nicht betroffen - _id bleibt der Dokumentfeldname in der Datenbank.

Schnellstart: Run starten und Output abrufen

Hier ist die minimale Abfolge, die ein Agent oder Skript benötigt, um einen Run zu starten und den vollständigen KI-Konversations-Output abzurufen:

Schritt 1 - Workflow-ID abrufen

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/workflows/list
# → { "data": [{ "id": "jx7...", "_id": "jx7...", "name": "My Workflow", ... }] }

Schritt 2 - Run starten

curl -X POST \
  -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "jx7...",
    "prompt": "Add a dark mode toggle to the settings page",
    "githubRepoUrl": "https://github.com/org/repo"
  }' \
  https://<deployment>.convex.site/api/v1/runs/start
# → { "data": { "id": "abc...", "status": "running" } }

Hinweis: githubRepoUrl ist in der Praxis erforderlich. Ohne diese URL hat die Sandbox keinen Projektcode, mit dem sie arbeiten kann, und Git-Operationen schlagen sofort mit exit status 128 fehl.

Schritt 3 - Warten, dann Runs auflisten, um die Run-ID abzurufen

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/runs?limit=5"
# → { "data": [{ "id": "r_abc...", "_id": "r_abc...", "status": "completed", ... }] }

Schritt 4 - Sandbox-IDs für den Run abrufen

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_abc..."
# → { "data": [{ "id": "s_xyz...", "_id": "s_xyz...", "status": "killed", ... }] }

Schritt 5 - Vollständigen Konversations-Output abrufen

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/messages?id=s_xyz..."
# → { "data": [{ "role": "assistant", "content": "...", "timestamp": ... }] }

Warum nicht /api/v1/runs/detail? Dieser Endpunkt liefert Run-Metadaten und Ausführungsschritte, aber NICHT den Text der KI-Konversation. Der eigentliche Agent-Output liegt in den Sandbox-Nachrichten.

API-Bereiche

Die API ist in die folgenden Bereiche gegliedert. Jeder ist auf einer eigenen Seite ausführlich dokumentiert:

Projektverwaltung -- 16 Endpunkte

Lesen, Aktualisieren und Löschen Ihres Projekts. Verwalten Sie Projekteinstellungen (System-Prompts, Umgebungsvariablen, Git-Konfiguration), Teammitglieder (einladen, entfernen, Rollen ändern), Provider-API-Schlüssel (E2B, Anthropic, GitHub usw.), Projekt-API-Schlüssel (erzeugen, widerrufen) und Projektzähler einsehen.

Workflows -- 10 Endpunkte

Workflow-Blueprints auflisten, abrufen, erstellen, aktualisieren, löschen, wiederherstellen, dauerhaft löschen, duplizieren, umbenennen und per Massenoperation löschen.

Personas -- 9 Endpunkte

KI-Agenten-Personas auflisten, abrufen, Analytics ansehen, erstellen, aktualisieren, löschen, duplizieren, aktivieren/deaktivieren und per Massenoperation löschen.

Runs -- 11 Endpunkte

Auflisten, abrufen, per Nummer abrufen (benutzerfreundliches runNumber-Lookup für Diagnose), nach Workflow oder Chain filtern, umbenennen, löschen, wiederherstellen, dauerhaft löschen, per Massenoperation löschen und neue Workflow-Runs starten. Enthält Felder für wiederkehrende Run-Planung (scheduledFor, timezone, recurrencePattern), CI-Check-Status, Fehlerdetails, Quality Scores, Token-Nutzung sowie Qualitäts- und Testergebnis-Details der Run-Schritte.

Issues, Sitzungen, Antwortsitzungen & Work Chains -- 30 Endpunkte

CRUD-Operationen für Issues (auflisten, abrufen, erstellen, aktualisieren, löschen, Run verknüpfen, per Massenoperation löschen). Verwaltung von Issue-Scanning-Sitzungen (auflisten, abrufen, umbenennen, löschen, wiederherstellen, dauerhaft löschen, per Massenoperation löschen, starten). Antwortsitzungen (auflisten, abrufen, erstellen, Status aktualisieren, löschen) und Sitzungsfragen (auflisten, prüfen, Annahme aktualisieren). Dazu Work Chains (auflisten, abrufen, Issues abrufen, erstellen, löschen, starten).

Sandboxes -- 7 Endpunkte

Sandboxes auflisten, abrufen, Nachrichten ansehen, umbenennen, löschen, wiederherstellen und dauerhaft löschen.

Learnings & Versionen -- 19 Endpunkte

Vollständiges Lifecycle-Management für Learnings (auflisten, Stats, Vorschau, nach Sandbox, erstellen, Status aktualisieren, Inhalt aktualisieren, löschen, wiederherstellen, dauerhaft löschen, Status-Massenupdate, per Massenoperation löschen) und Learning-Versionen (auflisten, abrufen, aktiv, kompilieren, aktivieren, deaktivieren).

Kontexte & Assets -- 31 Endpunkte

Verwalten Sie Kontexte (wiederverwendbare Projektwissens-Dokumente mit Versionsverlauf), Skills (wiederverwendbare Agent-Verhalten mit mehreren Dateien), Commands (KI-Befehle in einer einzigen Datei) und Skripte (ausführbare Automatisierungsskripte). Jeder Asset-Typ unterstützt vollständiges CRUD sowie versionierte Publish-Workflows.

Vorgänge -- 28 Endpunkte

Benachrichtigungen (auflisten, Anzahl ungelesener, als gelesen markieren, alle als gelesen markieren, verwerfen), Merging (auflisten, starten), Analytics (Nutzung, Tages-Stats, Zähler), Papierkorb (auflisten, wiederherstellen, dauerhaft löschen), Sprint-Chains (auflisten, abrufen, erstellen, löschen), wiederkehrende Aufgaben (auflisten, abrufen, erstellen, aktualisieren, löschen, umschalten), GitHub-Branches (auflisten, löschen), Pull Requests (auflisten, Merge auslösen) und Inbox-/Benachrichtigungs-REST-Endpunkte.

Webhooks & Callbacks

Behandlung von Clerk-Webhooks, interner Trigger.dev-Callback-Endpunkt (mit vollständiger Operationsreferenz, nach Domäne organisiert), Signaturverifizierung und Benachrichtigungsereignisse.

Legacy-Read-Only-Endpunkte

Die ursprünglichen 7 Read-Only-Endpunkte unter /api/v1/projects, /api/v1/workflows, /api/v1/runs, /api/v1/runs/detail und /api/v1/learnings bleiben aus Gründen der Abwärtskompatibilität verfügbar. Die neuen bereichsspezifischen Endpunkte (z. B. /api/v1/runs/list) liefern dieselben Daten zuzüglich Schreibvorgängen und weiteren Filteroptionen.

OpenAPI-Discovery

Die vollständige OpenAPI-3.1-Spezifikation wird live unter GET /api/v1/openapi.json bereitgestellt. Dieser Endpunkt erfordert keine Authentifizierung und ist der empfohlene Weg für LLM-Agenten und Tools, jeden Endpunkt, Parameter und jede Antwortstruktur zu entdecken, ohne auf die Docs-Site zugreifen zu müssen.

curl https://<your-deployment>.convex.site/api/v1/openapi.json

CORS

Alle /api/v1/*-Endpunkte unterstützen CORS über einen globalen OPTIONS-Preflight-Handler. Antworten enthalten den Header Access-Control-Allow-Origin: *.

Rate Limits

Die API übernimmt die Rate Limits der Convex-Plattform. Implementieren Sie für Integrationen mit hohem Durchsatz einen Exponential-Backoff bei 429-Antworten. Über die von Convex erzwungenen Limits hinaus gibt es keine zusätzlichen Per-Key-Rate-Limits.