For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/web/api.md (or send Accept: text/markdown).

Öffentliche API, Keys und Webhooks

Die versionierte REST-Oberfläche, gegen die deine Kunden bauen.

Zu dieser Anleitung fragen

Bevor Sie beginnen

Öffnen Sie Ihr heruntergeladenes Supastack-Projekt in Visual Studio Code über Datei → Ordner öffnen und wählen Sie dann Terminal → Neues Terminal. Das Repository-Stammverzeichnis ist der Ordner, der package.json, Apps und Pakete enthält. Führen Sie dort den Befehl unten aus und lassen Sie das Terminal geöffnet. Wenn ein Befehl nicht erkannt wird, lesen Sie die Installationsanleitung für das Tool durch, bevor Sie fortfahren.

Lesen Sie zuerst das Plattform-Tutorial. Ein Server ist der App-Prozess, der Browser- oder Telefonanfragen beantwortet. Web liest apps/web/.env.local, Expo liest apps/mobile/.env.local und Datenbankmigrationsbefehle lesen root .env. Die Demonstration ohne Datenbank /Dashboard ist getrennt von echten /Auth-Konten, die migriert werden müssen Postgres. Für eine reine Telefon- oder Desktop-Kaufabwicklung ist ein separat ausgeführtes Web-Backend erforderlich.

corepack pnpm --filter @supastack/web dev

Einrichtung und Konfiguration

packages/api definiert den versionierten Vertrag: Zod-Schemas für jeden Request und jede Response, den Error-Envelope und das OpenAPI-Dokument, das unter /api/v1/openapi ausgeliefert und unter /api/docs gerendert wird. Workspace-API-Keys werden unter Einstellungen → Entwickler erstellt; der Klartext wird einmal gezeigt, danach persistiert nur der gehashte Key.

Keys sind präfixiert (sk_<env>_…), gescoped (standardmäßig read) und werden bei jedem Request zu einem Workspace aufgelöst. Ausgehende Webhook-Abonnements werden über dieselbe Entwickler-Oberfläche verwaltet.

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Implementierungsablauf

Authentifiziere mit dem Bearer-Key; der Server löst den Workspace aus dem Key auf, nie aus einer client-gelieferten ID. Halte Response-Shapes versioniert — additive Änderungen innerhalb von v1, Breaking Changes hinter einer neuen Version.

Für ausgehende Webhooks abonniere eine Endpoint-URL auf den Event-Katalog; Deliveries werden signiert und aufgezeichnet, damit Konsumenten verifizieren und replayen können. Nutze webhook-events.ts für den Katalog und webhook-delivery.ts für Versuche.

Überprüfung und Fehlerbehebung

Verifiziere, dass ein widerrufener Key 401 zurückgibt, ein unterscoped Key verweigert wird und das OpenAPI-Dokument parst. Teste bei Webhooks Signaturverifikation, Redelivery nach Fehler und dass Event-Payloads nie Anbieter-Secrets tragen.