REST API 概要

Profound CMS REST API は、Rust 製の translation_manager サービスによって提供されています。レンダラーで使用されるヘッドレスの読み取り/ストリーム用エンドポイントに加えて、コンテンツ、翻訳、および CSV インポートの書き込みエンドポイントを公開しています。

すべての例では {CMS_API_URL} を CMS API ホストのベース URL（例: https://cms.dev.tryprofound.com）として使用します。グローバルなパス接頭辞はありません — ルートはルートディレクトリにマウントされます（例: {CMS_API_URL}/routes）。

認証

エンドポイントに応じて、API は 2 つの異なるスキームを使用します。

API キー（ヘッドレス読み取り + バリアントのアップサート）

キーは x-api-key ヘッダーまたは api_key クエリパラメーターとして送信します。

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

キーは WorkOS に対して検証され、短時間メモリにキャッシュされます。読み取り エンドポイントでは、サーバーが require_schema_api_key = true を設定している場合にのみ API キーが必要です。それ以外の場合は匿名での読み取りが許可されます。バリアントのアップサート（PATCH /dataset/{schema_name}）には、content_write 権限を持つ有効なキーが 常に 必要です。

API キー認証を使用するエンドポイント: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes。

ベアラー JWT（WorkOS）

管理用エンドポイントでは WorkOS ユーザーの JWT が必要です。

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

ベアラー認証を使用するエンドポイント: /translation, /translations, /usage, /csv。

ウェブサイト（テナント）の解決

API キーによるエンドポイントは、次の順序で対象のウェブサイトを解決します。

1. ?websiteId=<uuid> クエリパラメーター
2. Host ヘッダー（設定済みのウェブサイトドメインと照合）
3. CMS_WEBSITE_ID フォールバック（シングルテナント / ローカル開発）

いずれも有効な UUID に解決できない場合、エンドポイントは 400 を返します。

エラーモデル

ヘルスチェック

GET {CMS_API_URL}/health は { "status": "ok" } を返し、認証は不要です。可用性確認（liveness probe）に使用してください。