Visão geral da API REST

A API REST do Profound CMS é fornecida pelo serviço translation_manager em Rust. Ela disponibiliza endpoints headless de leitura/transmissão usados pelo renderizador, além de endpoints de escrita para conteúdo, tradução e importação de CSV.

Todos os exemplos usam {CMS_API_URL} como a URL base do host da sua API CMS (por exemplo https://cms.dev.tryprofound.com). Não há nenhum prefixo de caminho global — as rotas são montadas na raiz, por exemplo {CMS_API_URL}/routes.

Autenticação

A API usa dois esquemas distintos dependendo do endpoint.

Chave de API (leituras headless + upsert de variantes)

Envie a chave no cabeçalho x-api-key ou como o parâmetro de query api_key:

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <your-api-key>'

As chaves são validadas junto ao WorkOS e armazenadas em cache brevemente na memória. Para endpoints de leitura, uma chave de API só é necessária quando o servidor define require_schema_api_key = true; caso contrário, leituras anônimas são permitidas. O upsert de variantes (PATCH /dataset/{schema_name}) sempre exige uma chave válida com a permissão content_write.

Usa autenticação por chave de API: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.

JWT Bearer (WorkOS)

Os endpoints de gestão exigem um JWT de usuário do WorkOS:

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

Usa autenticação Bearer: /translation, /translations, /usage, /csv.

Resolução do site (tenant)

Os endpoints com chave de API resolvem o site de destino nesta ordem:

1. O parâmetro de query ?websiteId=<uuid>
2. O cabeçalho Host, confrontado com um domínio de site configurado
3. O fallback CMS_WEBSITE_ID (single-tenant / desenvolvimento local)

Se nenhum resolver para um UUID válido, o endpoint retorna 400.

Modelo de erros

Verificação de integridade

GET {CMS_API_URL}/health retorna { "status": "ok" } e não requer autenticação — use-o para sondas de vivacidade.