API: Grundlagen

Die API von VentionDesk ist dieselbe, die auch die Oberfläche benutzt. Für Automatisierungen — Claude, eigene Skripte, CI — meldest du dich mit einem API-Schlüssel an. Alle Adressen beginnen mit https://api.ventiondesk.com; alle Rümpfe und Antworten sind JSON in UTF-8.

Anmelden mit einem API-Schlüssel

Einen Schlüssel legt der Inhaber unter Einstellungen › Rollen & Zugänge › „Neuer Schlüssel" an. Er erscheint genau einmal im Klartext.

Jede Anfrage trägt ihn als Bearer-Token:

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

Einen eigenen Endpunkt zum Tauschen gibt es nicht: VentionDesk erkennt den Schlüssel am Präfix, prüft ihn bei jeder Anfrage (zurückgezogen? abgelaufen?) und arbeitet danach mit einer Sitzung für das Konto dieses Schlüssels. Für den Schlüssel gelten damit dieselben Datenbankregeln wie für einen Menschen — er sieht nur, was sein Zuschnitt erlaubt.

Ein Agenten-Schlüssel ist ein eigenes Konto mit der Rolle Agent. Gedacht ist er für die Endpunkte, an denen in der API-Referenz ein Scope steht, dazu GET /v1/me und die Agenten-Läufe. Endpunkte, die „Inhaber" oder „Inhaber und Mitarbeitende" verlangen, bedient die Weboberfläche mit der Sitzung eines angemeldeten Menschen; einem API-Schlüssel antworten sie mit 403.

Scopes

Was ein Agenten-Schlüssel darf, bestimmen seine Scopes:

Ein Scope steht an genau den Endpunkten, die ihn einlösen — die API-Referenz nennt ihn je Endpunkt. deployments:read steht an keinem Endpunkt: Er wirkt über die Datenbankregeln der gespiegelten Commits, Pull Requests und Deployments.

Projektbindung

Ein Schlüssel gilt für alle Projekte oder für eine Auswahl. Ein gebundener Schlüssel sieht nur Daten seiner Projekte — und bewusst nichts ohne Projektbezug, etwa Vorgänge, die noch keinem Projekt zugeordnet sind. Eine Zeile außerhalb seiner Projekte beantwortet die API mit 404 oder 403. Ein Eingangs-Schlüssel ist immer an genau ein Projekt gebunden.

Zuschnitt ändern heißt neuer Schlüssel. Scopes und Projekte eines Schlüssels lassen sich nachträglich nicht ändern: Lege einen neuen an und ziehe den alten zurück. Ein zurückgezogener oder abgelaufener Schlüssel wird bei der nächsten Anfrage abgewiesen.

Fehler

Jede Fehlerantwort hat dieselbe Form:

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error ist ein deutscher Satz für Menschen, code ein stabiler englischer Wert für Programme. Häufige Antworten:

Jede Antwort trägt eine Kennung im Kopf x-request-id. Schickst du selbst eine mit (bis 128 Zeichen), wird sie übernommen. Nenne sie dem Support, wenn etwas schiefgeht.

Rate Limits

Gezählt wird je Minute, je Schlüssel oder je IP-Adresse:

Über der Grenze antwortet die API mit 429 und rate_limited; die Kopfzeilen RateLimit und RateLimit-Policy nennen Stand und Grenze.

Listen und Filter

Listen-Endpunkte filtern über Abfrageparameter und begrenzen mit limit; Seiten mit Cursor oder Offset gibt es nicht. Beispiele:

• GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20 — Aufgaben, die gerade gezogen werden können.
• GET /v1/projects?status=active — aktive Projekte.

Welche Parameter ein Endpunkt kennt und welche Felder er zurückgibt, steht in der API-Referenz — gelesen aus demselben Vertrag, mit dem VentionDesk die Anfrage prüft.

Die typische Runde eines Agenten

1. GET /v1/tasks?claimable=true — was ist zu tun?
2. POST /v1/tasks/:id/claim — die Aufgabe atomar übernehmen. Zwei Läufe bekommen nie dieselbe.
3. Arbeiten; zwischendurch POST /v1/tasks/:id/result mit "state": "arbeitet" als Lebenszeichen.
4. POST /v1/tasks/:id/result mit kontrolle, frage, master, blockiert oder erledigt — bei kontrolle und erledigt mit Beleg in evidence.

Wer das nicht selbst bauen will, nimmt Claude und MCP.