URL di base, schemi di autenticazione, risoluzione del tenant e modello di errore per l'API REST del CMS.
L'API REST di Profound CMS è fornita dal servizio Rust translation_manager. Espone endpoint headless di lettura/streaming utilizzati dal renderer, oltre a endpoint di scrittura per i contenuti, le traduzioni e l'importazione CSV.
Tutti gli esempi usano {CMS_API_URL} come URL di base dell'host della tua API CMS (ad esempio https://cms.dev.tryprofound.com). Non esiste alcun prefisso di percorso globale — le route sono montate alla radice, ad es. {CMS_API_URL}/routes.
L'API utilizza due schemi distinti a seconda dell'endpoint.
Invia la chiave come intestazione x-api-key oppure come parametro di query api_key:
curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
-H 'x-api-key: <your-api-key>'
Le chiavi vengono convalidate tramite WorkOS e memorizzate temporaneamente in cache. Per gli endpoint di lettura, è richiesta una chiave API solo quando il server imposta require_schema_api_key = true; in caso contrario sono consentite letture anonime. L'upsert delle varianti (PATCH /dataset/{schema_name}) richiede sempre una chiave valida che includa l'autorizzazione content_write.
Utilizza l'autenticazione con chiave API: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.
Gli endpoint di gestione richiedono un JWT utente WorkOS:
curl '{CMS_API_URL}/usage?orgId=<uuid>' \
-H 'Authorization: Bearer <workos-jwt>'
Utilizza l'autenticazione Bearer: /translation, /translations, /usage, /csv.
Gli endpoint con chiave API determinano il sito web di destinazione in questo ordine:
?websiteId=<uuid>Host, confrontata con un dominio del sito web configuratoCMS_WEBSITE_ID (single-tenant / sviluppo locale)Se nessuno di questi produce un UUID valido, l'endpoint restituisce 400.
| Stato | Significato |
|---|---|
400 | Richiesta non valida — websiteId mancante/non valido, UUID non valido o errore di validazione |
401 | Credenziali mancanti o non valide |
403 | Autenticato ma privo di un'autorizzazione necessaria |
404 | Risorsa non trovata |
500 | Errore interno / del database |
GET {CMS_API_URL}/health restituisce { "status": "ok" } e non richiede autenticazione — usalo per i controlli di vivacità.