サイト / CMS API を使う
API v1 でプラットフォームや独立 CMS の認証、コンテンツ編集、公開を行います。
サイト / CMS API を使う
API v1 は外部システムとサイト・CMS データを接続します。利用する環境の契約を確認し、権限を限定したキーを作成して、バージョンを保護しながら下書きを保存します。
サービスと配置方式を選ぶ
QOKIT_API_URL に API サービスのオリジン(ローカルでは http://localhost:7777)または独立インストールのオリジンを設定します。QOKIT_PROJECT_ID はプロジェクト ID です。エクスポートでは data/seed.json の project.id に保存されます。公開読み取りにはプロジェクトの slug を使います。
| 配置方式 | 機能 |
|---|---|
| プラットフォーム | CMS 管理、エクスポート、プラットフォームでの公開 |
cms-managed | ローカル CMS 管理とサイト描画 |
cms-only | ローカル CMS 管理と公開 headless 読み取り。サイト描画なし |
site-only | 静的 HTML ページとアセットのみ。実行時 API なし |
契約を確認する
各サービスは対応する操作のみを提示します。非対応の操作は 404 を返します。API 1.0 は既存のバージョンなしルートとの互換性を維持します。
| パス | 用途 |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1:本文、応答、権限、前提条件 |
GET /v1/capabilities | API バージョン、配置方式、対応操作 |
GET /v1/sdk/client.mjs | 依存関係なしの JavaScript クライアント |
GET /v1/sdk/client.d.mts | 対応する TypeScript 型宣言 |
API キーを作成する
プラットフォームへのログイン完了後に得た accessToken を SESSION_TOKEN として使います。サイト設定の管理権限が必要です。キーを発行する前に必要な認証を完了してください。
curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'独立 CMS では配置所有者のメールアドレスとパスワードでログインし、セッション Cookie を保存してからキーを作成します。
curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'作成時にのみ token が返ります。サーバー環境変数 QOKIT_SITE_API_KEY に保存してください。リクエストには qk_site_ で始まる Bearer トークンを使います。有効期間は既定で 90 日、1–365 日で指定でき、プロジェクトあたり有効なキーは最大 50 個です。設定管理権限のあるログインセッションで GET /v1/projects/{id}/api-keys により一覧表示し、DELETE /v1/projects/{id}/api-keys/{keyId} により失効させます。
必要な権限だけを選びます。作成者の現在のアクセス権と権限は各リクエストで再確認されます。期限切れ、失効、ロール変更は後続リクエストから有効です。API キーで他のキーは管理できません。
| Scope | 用途 |
|---|---|
content:read / content:write | コレクションとエントリーの読み取り / 編集 |
content:publish | 明示的な公開とエントリーを公開する書き込み |
pages:read / pages:write | runtime の読み取り / ページ内容、構造、SEO、フォームの編集 |
media:read / media:write | メディアとフォルダーの読み取り / 管理 |
settings:read / settings:write | サイト設定の読み取り / 編集 |
users:read / users:write | CMS ユーザーの読み取り / 管理 |
leads:read / leads:write / analytics:read | 見込み客の読み取り / 更新と CMS ダッシュボードの読み取り |
marketing:read / marketing:write | マーケティングコンテンツの読み取り / 生成 |
deployments:read / deployments:write | プラットフォームのエクスポート・公開ジョブ |
sync:write / updates:read / updates:write | 独立インストールの同期と署名付き更新 |
SDK で下書きを保存する
ワークスペースパッケージは @qokit/site-api です。npm にはまだ公開されていません。外部プロジェクトではクライアントの 2 ファイルを sdk にダウンロードします。新しいエクスポートには同梱済みです。
mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mtsこの例には content:read と content:write が必要です。en を有効なプロジェクト言語に置き換えます。新しいサンプルコレクションを作成するため、再実行時には既存のコレクション ID を再利用してください。
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({
baseUrl: process.env.QOKIT_API_URL,
projectId: process.env.QOKIT_PROJECT_ID,
token: process.env.QOKIT_SITE_API_KEY
});
const collection = await api.collections.create({
key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);下書きの保存では、公開済みエントリーの以前の公開スナップショットが維持されます。確認後、content:publish を持つキーで保存済みバージョンを明示的に公開できます。プラットフォームのページ編集はサイト公開処理が完了するまで下書きです。
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });復元時は api.entries.revisions(id) を読み取り、api.entries.restore(id, revisionId, { expectedUpdatedAt }) を呼び出します。他の操作には api.request(path, options) を使い、idempotencyKey も指定できます。クライアントは書き込みを自動再試行しません。
管理ルート
これらのパスには /v1/projects/{id} を付けます。全操作、フィールド、環境ごとの要件は OpenAPI で確認できます。DELETE はコレクション、エントリー、メディアをアーカイブします。
| パス | メソッド |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, POST |
/cms/media/{assetId}, /cms/media/folders/{folderId} | PUT, DELETE |
/runtime, /content/{locale} | GET; PUT /content/{locale} |
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
プラットフォームのメディアは URL 登録とアップロード準備に対応します。独立環境では fileName、contentType、contentBase64 を使い、ファイル上限 10 MB とシグネチャ検証が適用されます。プラットフォームのユーザー変更には Idempotency-Key、ローカルユーザー作成には 12–1024 文字のパスワードが必要です。CSV、一括書き込み、翻訳関連付けはプラットフォーム拡張です。
バージョン、ページ分割、エラー
更新、アーカイブ、履歴復元には expectedUpdatedAt を指定し、最後に読み取った updatedAt の値を使います。欠落時は 428、古い値は 409 を返します。
ページ構造、SEO、フォームでは GET /v1/projects/{id}/runtime を読み取り、content.updatedAt と siteVersion.updatedAt を baseContentUpdatedAt と baseSiteVersionUpdatedAt として送信します。プラットフォームでは Builder の履歴と有効な編集リースも検証します。
一覧の既定値は page=1&pageSize=24、1 ページ最大 100 件です。管理一覧は items、公開一覧は entries を返します。履歴とフォルダーは配列です。コンテンツをエクスポートする際は全ページを読み取ります。
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}応答には X-Request-Id と X-Qokit-Api-Version が含まれます。エラーは安定したコードとリクエスト ID を返します。
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}401 ではキーの有効性、403 では権限と作成者のアクセスを確認します。409 では再読込して変更を比較し、428 ではバージョンを指定します。429 では Retry-After に従います。キー / アドレスごとに毎分 300 リクエストで、プラットフォームには追加の IP・書き込み制限があります。
独立インストールの設定
プラットフォームのブラウザー連携は CORS_ALLOWED_ORIGINS を使います。独立環境のキーを使うブラウザー呼び出しは SITE_API_ALLOWED_ORIGINS に正確なオリジンを指定します。Cookie 管理は同一オリジンです。公開 CMS 読み取りには CMS_ALLOWED_ORIGINS も使えます。CMS-only のメディア URL は CMS_PUBLIC_URL を設定します。
データディレクトリとアップロード全体を、非公開の data/api-security.json と data/api-revisions.json を含めてバックアップします。パスワードとキーはハッシュとしてローカルに保持されます。各データディレクトリには 1 つの Node 書き込みプロセスを使います。
古いエクスポートは署名付き runtime 更新で v1 を取得します。更新後は HTTP で現在の契約とクライアントを取得します。同梱ファイルはエクスポート時点のスナップショットです。
認証情報なしの公開読み取りについては次を参照してください: 公開コンテンツ API を呼び出す.
最終更新