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/modules/api.md (or send Accept: text/markdown).

API-Modul

Der versionierte öffentliche Vertrag, Key-Plumbing und die OpenAPI-Oberfläche.

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 ist die Quelle der Wahrheit für die öffentliche REST-Oberfläche: Zod-Schemas für Requests, Responses und den Error-Envelope plus das OpenAPI-Dokument (openApiDocument), das unter /api/v1/openapi serviert wird. Route-Handler komponieren diese Schemas statt Shapes neu zu definieren.

API-Keys werden pro Workspace mit sk_<env>_-Präfix ausgestellt, gehasht mit Constant-Time-Comparison gespeichert und tragen Scopes — standardmäßig read. api-keys.ts besitzt Erstellung, Lookup und Widerruf.

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

Implementierungsablauf

Füge Endpunkte innerhalb der existierenden Version hinzu: erweitere Schemas, halte den Error-Envelope und regeneriere die OpenAPI-Oberfläche, damit /api/docs korrekt bleibt. Breaking Changes bekommen eine neue Version, keine stille Shape-Änderung.

Löse den Workspace des Callers aus dem präsentierten Key auf, wende dieselben Entitlement- und Validierungsregeln wie die Web-App an und rate-limit pro Key.

Überprüfung und Fehlerbehebung

Contract-teste jedes Route-Shape gegen die Paket-Schemas. Verifiziere, dass unbekannte Keys, widerrufene Keys und underscoped Requests alle mit dem dokumentierten Error-Envelope fehlschlagen und dass das OpenAPI-Dokument gültiges JSON bleibt.