HTTP-API v1 — Orientierung für Drittentwickler

Kanonische Referenz auf dem Core-Host (relativ): /docs/http-api-v1 · Produkt-URL: https://apinterface.com/docs/http-api-v1

Grundlagen

Alle Endpunkte liegen unter dem Präfix /api/v1; Antworten sind JSON (Ausnahmen: leere 204).
Maschinenlesbare Übersicht: GET /api/v1/openapi.json (OpenAPI 3.0, Kernpfade; dynamische Modul-Routen siehe unten).
Öffentlich ohne Login: u. a. GET /api/v1/health, GET /api/v1/meta/scopes, GET /api/v1/meta/build, GET /api/v1/openapi.json.
Header X-Request-Id auf jeder Antwort; bei HTTP-Fehlern (≥400) zusätzlich Feld requestId im JSON-Body.
Rate-Limit pro IP (Standard siehe Core-Env APINTERFACE_API_V1_RPM); OPTIONS (CORS-Preflight) zählt nicht.

Header: Authorization: Bearer <apif_…>. Token ist an Nutzer + Firma gebunden.
Erzeugung durch Firmen-Superuser in der Web-UI: /settings/api-tokens (nach Login, aktive Firma).
Bekannte Scopes: GET /api/v1/meta/scopes — u. a. api.self.read, api.tokens.read, api.tokens.manage, api.audit.read, api.modules.invoke.

Mutierende Aufrufe an /api/v1/account/tokens erfordern X-CSRF-Token (Wert wie in der Session / auf der PAT-Einstellungsseite angezeigt) plus Firmen-Superuser.
Alternative für Automation: PAT mit api.tokens.manage (ohne CSRF).

Wenn der Core die Umgebungsvariable API_CORS_ORIGINS setzt (kommagetrennte, exakte Origins), antwortet /api/v1 mit passenden CORS-Headern inkl. Access-Control-Allow-Credentials: true und Access-Control-Expose-Headers: X-Request-Id.

Datei im Modul-Release: src/api/registerApiV1.js, Export registerApiV1(router, { moduleKey, releaseDir, requireApiScope }).
Mount durch den Core: /api/v1/modules/<manifest-id>/… (Manifest-Feld id aus src/index.js / Manifest).
Der aufrufende Client muss ein PAT mit Scope api.modules.invoke verwenden; die Firma des Tokens muss das Modul wie in der Web-UI aktiv haben (Apps / Mandant).
Im Paket-Manifest (Schema /schema/module.manifest.json): "httpApiV1": true kennzeichnet die API-Fähigkeit; optional apiV1Module mit Kurztext und Link zu eurer Modul-API-Doku.

Architektur & Mandanten: /docs/modulentwicklung
Cursor/Meta-Regel (Kurzfassung): Repository-Datei .cursor/rules/apinterface-http-api.mdc
Core-Repo: .github/copilot-instructions.md (Abschnitt HTTP-API)