REST API Overview

Die Profound CMS REST-API wird vom Rust-Dienst translation_manager bereitgestellt. Sie stellt headless Lese-/Streaming-Endpunkte bereit, die vom Renderer verwendet werden, sowie Schreibendpunkte für Inhalte, Übersetzungen und den CSV-Import.

Alle Beispiele verwenden {CMS_API_URL} als Basis-URL Ihres CMS-API-Hosts (z. B. https://cms.dev.tryprofound.com). Es gibt kein globales Pfadpräfix — Routen werden im Root eingehängt, z. B. {CMS_API_URL}/routes.

Authentifizierung

Die API verwendet je nach Endpunkt zwei unterschiedliche Verfahren.

API-Schlüssel (headless Lesezugriffe + Variant-Upsert)

Senden Sie den Schlüssel als x-api-key-Header oder als Abfrageparameter api_key:

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <Ihr-API-Schlüssel>'

Schlüssel werden gegenüber WorkOS validiert und kurzzeitig im Speicher zwischengespeichert. Für Lese-Endpunkte wird ein API-Schlüssel nur benötigt, wenn der Server require_schema_api_key = true setzt; andernfalls sind anonyme Lesezugriffe erlaubt. Das Variant-Upsert (PATCH /dataset/{schema_name}) erfordert immer einen gültigen Schlüssel mit der Berechtigung content_write.

Verwendet API-Schlüssel-Authentifizierung: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.

Bearer-JWT (WorkOS)

Verwaltungsendpunkte erfordern ein WorkOS-User-JWT:

curl '{CMS_API_URL}/usage?orgId=<uuid>' \
  -H 'Authorization: Bearer <workos-jwt>'

Verwendet Bearer-Authentifizierung: /translation, /translations, /usage, /csv.

Auflösung der Website (Mandant)

API-Schlüssel-Endpunkte ermitteln die Ziel-Website in folgender Reihenfolge:

1. Der Abfrageparameter ?websiteId=<uuid>
2. Der Host-Header, abgeglichen mit einer konfigurierten Website-Domain
3. Das Fallback CMS_WEBSITE_ID (Single-Tenant / lokale Entwicklung)

Wenn keiner davon zu einer gültigen UUID aufgelöst werden kann, gibt der Endpunkt 400 zurück.

Fehlermodell

Health-Check

GET {CMS_API_URL}/health gibt { "status": "ok" } zurück und erfordert keine Authentifizierung — verwenden Sie ihn für Liveness-Probes.