REST API リファレンス

EmDash は、サポート対象のアプリケーション プログラミング インターフェース（API）を /_emdash/api/ 配下で公開しています。リクエスト パラメーター、ボディ、レスポンス スキーマ、ステータス コード、クライアント生成には、生成された OpenAPI 3.1 ドキュメントを使用してください。

GET /_emdash/api/openapi.json

このドキュメントは API が使用する Zod スキーマと同じものから生成されます。設定されたメディア アップロードの最大サイズも反映されます。

公開契約の境界

OpenAPI ドキュメントが、サポート対象 REST API の境界です。EmDash には管理画面やプロトコル ワークフロー用のルートもあります。ソースツリーに存在するが OpenAPI にないルートは、外部クライアント向けのサポート対象 REST 操作ではありません。

この区別は、バックアップ、バイライン管理、リレーション走査、プラグイン管理、セットアップ、インポート、認証の各ルートに当てはまります。バックアップは バックアップ ガイド を、サポート対象のバイライン管理は MCP バイライン ツール を使用してください。OAuth エンドポイントはプロトコル エンドポイントです。MCP OAuth セクション で説明するメタデータから発見し、アプリケーション REST エンドポイントとして扱わないでください。

認証と認可

ほとんどの操作は、EmDash セッション Cookie または Bearer トークンのいずれかを受け付けます。パーソナル アクセス トークンまたは OAuth アクセス トークンを Authorization ヘッダーで送信します。

Authorization: Bearer $EMDASH_TOKEN

Bearer トークンはスコープと関連ユーザーのロールによって制限されます。セッション リクエストはユーザーのロールを使用します。認可モデルは ユーザーロール と トークン スコープ を参照してください。

GET および POST /_emdash/api/comments/{collection}/{contentId} は公開です。GET は承認済みコメントを返し、POST はモデレーション用にコメントを送信します。残りのコメント モデレーション操作には認証が必要です。

クロスサイト リクエスト フォージェリ（CSRF）対策

セッション Cookie で認証する状態変更リクエストには、次のヘッダーを含めます。

X-EmDash-Request: 1

Bearer トークン リクエストはブラウザの暗黙的資格情報を使わないため、このヘッダーは不要です。公開の書き込み操作へのブラウザ リクエストは、ヘッダーを送るか、EmDash サイトの公開またはリクエスト オリジンと一致する Origin を持つ必要があります。

レスポンス エンベロープ

成功した JSON レスポンスは success を true にし、操作固有の結果を data に置きます。

{
	"success": true,
	"data": {
		"items": []
	}
}

エラーでは success が false になり、安定した機械可読コードとメッセージが含まれます。一部のエラーには構造化された details もあります。

{
	"success": false,
	"error": {
		"code": "NOT_FOUND",
		"message": "Content item not found"
	}
}

各 OpenAPI 操作のステータス コードとエラー スキーマを使用してください。一般的なステータスは、無効な入力の 400、資格情報の欠如または無効の 401、スコープまたは権限不足の 403、リソース不在の 404、状態競合の 409、サイズ超過アップロードの 413、プラグインによる保存拒否の 422、内部障害の 500 です。

エンドポイント一覧

操作 ID は生成された契約内で安定しており、OpenAPI クライアント生成器ではメソッド名としてよく使われます。次の一覧は生成された OpenAPI ドキュメントと照合されています。

コンテンツ

メディア

スキーマ

コメント

タクソノミ

メニュー

セクション

ウィジェット

設定

検索

リダイレクト

ユーザー

転送

コンテンツ ライフサイクルとバイライン

コンテンツ ライフサイクル リファレンス は、REST、MCP、CLI、管理パネルで共有される状態、リビジョン、権限、競合、フックの動作を定義します。

コンテンツの読み取りでは、利用可能な場合に不透明な _rev トークンが返されます。読み取り以降に行われた変更の上書きを防ぐため、PUT /content/{collection}/{id} に _rev を付けて送信します。古いトークンは競合を起こします。再試行する前に項目を再度読み取ってください。CLI では content update でこのチェックが必須ですが、REST では意図的に無条件書き込みを選ぶクライアント向けにフィールドは任意のままです。

エントリーの読み取りと更新

変更する前にエントリーを読み取ります。

GET /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN

レスポンスにはフィールド、公開状態、リビジョン トークンが含まれます。

{
	"success": true,
	"data": {
		"item": {
			"id": "01JARTICLE0000000000000000",
			"type": "articles",
			"slug": "launch-notes",
			"status": "published",
			"data": { "title": "Launch notes" }
		},
		"_rev": "opaque-revision-token"
	}
}

変更が必要なフィールドだけを、その読み取りで得たトークンと一緒に送信します。

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"_rev": "opaque-revision-token"
}

公開済みエントリーを変更すると、以前のバージョンがライブのまま下書きが作成されます。compare 操作で両方のバージョンを確認し、下書きを公開するか破棄します。公開取り消しではコンテンツと公開日は保持され、保留中のスケジュールはキャンセルされ、エントリーはライブ サイトから削除されます。

作成および更新ボディはバイライン クレジットを受け付け、コンテンツ レスポンスにはプライマリ バイラインと順序付きクレジットが含まれます。コンテンツ一覧は保存されたバイライン ID でフィルターでき、著者の推論バイラインを任意で含められます。バイライン レコード自体の作成と管理は、公開 REST 契約ではなく MCP バイライン ツール で行います。

ライフサイクル操作はソフト削除と完全削除を区別します。復元はゴミ箱のコンテンツをスケジュールなしの下書きとして返します。完全削除はゴミ箱の項目を削除し、元に戻せません。publish、unpublish、schedule、unschedule、compare、discard-draft、duplicate は別操作なので、クライアントは一度に 1 つの状態遷移を要求できます。

エントリー編集ロック

コレクションでは、編集者がエントリーを開いたときに 7 分間の編集ロックを取得できます。/content/{collection}/{id}/lock の 3 操作で、読み取り、取得または更新、リース解放を行います。

読み取りまたは取得レスポンスは、ロックが有効か、呼び出し元がリースを保持しているか、現在誰が保持しているかを示します。

{
	"success": true,
	"data": {
		"enabled": true,
		"heldByCaller": false,
		"holder": {
			"userId": "01JUSER000000000000000000",
			"userName": "Ada",
			"acquiredAt": "2026-05-01T09:12:04.117Z",
			"expiresAt": "2026-05-01T09:19:04.117Z"
		}
	}
}

コレクションで編集ロックが無効の場合、enabled は false でリースは取得されません。同じロックを再度取得したりエントリーを保存したりすると、呼び出し元が保持するリースが延長されます。

取得ボディには、1 つの編集セッションを識別する不透明な token と、別の編集者のリースを置き換えるときの takeover: true を含められます。ロック解放時は同じトークンをクエリ パラメーターで渡します。同じアカウントの 2 番目のタブが、誤って 1 番目のタブのリースを解放することはありません。

別ユーザーがリースを保持しているとき、保護されたコンテンツ書き込みは 409 ENTRY_LOCKED を返します。エラー詳細に保持者と有効期限が示されます。ロックを上書きするには、ボディのある書き込みでは JSON ボディに "overrideLock": true を、ボディのない DELETE では ?overrideLock=true を送ります。

参照選択

reference フィールド は、リレーションを通じてエントリーを別コレクションのエントリーにリンクします。値は data の一部ではなく、翻訳グループをキーにするため、エントリーの各翻訳は 1 つの選択を共有します。

作成および更新ボディは references 配下に選択を持ち、フィールド スラッグをキーに、表示順のエントリー ID を最大 1000 件の配列とします。EmDash はエントリーと同じトランザクションで選択を書き込みます。次の更新はエントリーの著者を置き換えます。

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"references": { "author": ["01JAUTHOR00000000000000000"] },
	"_rev": "opaque-revision-token"
}

リレーションの子側にバインドされたフィールドは、書き込み対象を指すエントリーを選択し、それ自体の順序は持ちません。リレーション制限は両端で適用されるため、リンク先エントリーに許容より多い親を与える選択は、自身が多すぎるエントリーをリンクする場合と同様に拒否されます。

リビジョンを保持するコレクションでは、公開エントリーで変更した選択は、エントリーの他の保留編集とともに下書きにステージされます。エントリー公開時にライブになり、下書き破棄とともに捨てられます。公開時に選択全体がリレーション制限に対して再チェックされます。

単一エントリー読み取りは、フィールド スラッグをキーにした references を返します。各フィールドはリンク先エントリーの最初のページ（50 件）を保持し、さらに多い場合は nextCursor を返し、各エントリーの ID、スラッグ、コレクション、表示タイトル、解決済みロケール、翻訳グループを報告します。下書きを読める呼び出し元は、下書きにステージされた選択を見られます。コンテンツ一覧操作には references は含まれません。

リレーション定義とリンク走査は管理ルートで、OpenAPI になく公開契約外です。上記のコンテンツ操作で選択を読み書きし、サイトでは getEmDashEntry() と getEmDashReferences() で描画します。

翻訳

公開 REST 契約は、コンテンツ翻訳とタクソノミ定義の翻訳を公開します。コンテンツ作成は translationOf を受け付け、タクソノミ作成も同じフィールドでロケール variant を追加します。コンテンツ用語操作はロケールを意識した割り当てを返します。

GET /taxonomies/{name} は locale 省略時にサイトのデフォルト ロケール定義を返し、デフォルト ロケールに定義がない場合のみ最小ロケール コードにフォールバックします。更新は異なります。locale 省略時は最小ロケール コードの定義を変更します。翻訳タクソノミの更新を意図した定義に届けるには locale を渡してください。そのロケールに定義がなければ、別ロケールにフォールバックせず NOT_FOUND を返します。translations 操作は共有グループ内のすべての定義を返し、translationOf が受け付ける ID を提供します。

label と labelSingular は 1 ロケールの定義に属します。hierarchical と collections はタクソノミに属し、すべてのロケールが同じ値を返し、いずれかを送る更新はすべてのロケールで変更します。別ロケールに既存の名前の定義を作成すると、リクエストが translationOf を送るかどうかに関わらずそのタクソノミに追加されます。新定義はタクソノミの hierarchical と collections を引き継ぎ、異なる値を送る create は VALIDATION_ERROR を返します。

タクソノミ削除は、定義の全ロケール、すべての用語、それらのコンテンツ割り当てを削除します。コンテンツ エントリー自体は削除しません。

用語並べ替え操作は 1 つの兄弟グループを変更します。ids 配列はそのグループの一部のみ含められ、列挙した用語は既存位置を交換し、省略した用語はそのままです。例: [A, B, C] を ids: ["C", "A"] で並べ替えると [C, B, A] になります。並べ替えは親子関係を変えず、1 つの用語順序が翻訳グループ内の全ロケールに適用されます。

メニュー、タクソノミ用語、バイラインの翻訳ルートは公開 REST 契約にありません。サポートされる翻訳一覧は MCP サーバー の menu_translations、taxonomy_term_translations、byline_translations で利用できます。

メディア エンドポイント

メディア操作は、一覧、アップロード、メタデータ更新、画像置換、フォルダー、使用情報、使用インデックス保守をカバーします。メディア ライブラリ ガイド がユーザー向けワークフローと使用カバレッジの意味を説明します。

メディアの一覧と確認

GET /media はカーソルまたは番号付きページのページネーション、MIME タイプとファイル名フィルター、フォルダー、任意の使用サマリーに対応します。すべてのフォルダーを含めるには folderId を省略し、メイン ライブラリのみには folderId=unfiled を渡します。一覧または単一項目読み取りで includeUsage=1 を設定すると使用情報を含めます。他の値は無効です。

usage.count は、現在のインデックス済みソースがメディア項目を参照する、重複のないアクティブなコンテンツ行またはロケールに加え、それを選択する各サイト設定（logo、favicon、seo.defaultOgImage）を数えます。1 エントリー内の重複参照は 1 回とし、ゴミ箱のエントリーは数えません。この数値は下書きを読める呼び出し元にのみ表示されます。他の認可済みメディア読者は count: null を受け取ります。カウントが下書きコンテンツを漏らす可能性があるためです。

GET /media/{id}/usage は参照元コンテンツ エントリーをページで返します。各ページには siteSettings（メディア項目を選択するサイト設定、例: [{ "setting": "favicon" }]）も含まれます。サイト設定はリクエストごとに保存設定から読み取られ、使用インデックスに依存しません。

各使用結果にはカバレッジ状態が含まれます。

インデックス対象フィールド型内でゼロ件数を完全とみなせるのは complete のみです。同時書き込み中の件数は参考値であり、メディア項目をロックしたり削除が安全であることを保証しません。使用インデックスは画像・ファイルフィールド、リピーター画像フィールド、Portable Text の画像・ギャラリー ブロック、EmDash コレクションで保持ブロック バージョンが宣言するメディアをカバーします。サイト ロゴ、favicon、デフォルト SNS 画像設定も報告されます。使用にはカスタム Portable Text ブロック、アプリケーション コード、レンダリング HTML、その他設定、メニュー、ウィジェット、プラグイン データ、外部サイト、プロバイダー専用アセットは含まれません。

直接マルチパート アップロード

マルチパート リクエストの file フィールドとしてファイルを POST し、EmDash 経由で送信します。

curl --request POST \
	--header "Authorization: Bearer $EMDASH_TOKEN" \
	--form "file=@./cover.jpg;type=image/jpeg" \
	https://example.com/_emdash/api/media

curl はマルチパート境界を付加します。Content-Type ヘッダーは手動で設定しないでください。OpenAPI の MediaDirectUploadBody スキーマが任意メタデータ フィールドを列挙し、レスポンス スキーマは新規アップロードと重複排除された既存項目を区別します。

マルチパート ボディには画像の width、height、適用すべき MIME タイプ許可リストを持つ fieldId、低品質プレースホルダー用の縮小 thumbnail も含められます。新規ファイルは 201 Created を返し、すぐに利用可能です。同一バイト列は既存メディア項目を 200 OK と deduplicated: true で返します。

アップロード先フロー

クライアントが S3 互換ストレージに直接アップロードできる場合はアップロード先フローを使用します。確認が成功するまでメディア項目は pending のままで、標準ライブラリに表示されません。

ローカル ストレージとネイティブ R2 は同一 origin の EmDash アップロード先を返します。S3 互換ストレージは署名付き外部 URL を返す場合があります。pending 項目は確認成功まで標準メディア一覧から除外されます。

アップロード エラー

次のエラーは別の回復操作が必要です。

メディア フォルダー

フォルダー名はトリムされ 200 文字に制限され、Unicode 正規化と小文字化後に比較されます。Photos、photos、ＰＨＯＴＯＳ などは競合します。フォルダー削除はメディアをメイン ライブラリに戻します。メディア削除、メディア ID や URL の変更、使用レコードの変更は行いません。

メディア使用の修復

メディア使用の有効化、進捗、ワーク キュー、削除クリーンアップ、修復は /_emdash/api/admin/media-usage/ 配下のオペレーター操作です。セッション ユーザーには schema:manage が必要です。Bearer トークンには admin スコープも必要です。

追跡がオフの場合、有効化前に直接 DB 書き込みを一時停止してください。セットアップ中 EmDash は API 経由のコンテンツとスキーマ書き込みを一時ブロックしますが、DB に直接書き込む別プロセスは止められません。

書き込みリクエストがタイムアウトまたは 409 / 500 を返した場合、再試行前に有効化と進捗状態を読み取ってください。完了バッチは記録されたままです。lastErrorCode が設定されている場合、直接書き込みを止めたまま報告された問題を解決し、確認済み再試行を 1 回送ります。有効化開始後はキャンセルまたはリセットできないため、ステージング副本で手順を試し、最新の DB バックアップを保持してください。

ワーク一覧操作は、コンテンツ、メディア参照、リース トークン、生 DB エラー、正確なバックログ件数を返さずに、失敗または遅延したエントリー インデックス作成を公開します。1 項目の再試行は冪等です。409 WORK_LEASE_ACTIVE はワーカーがまだ項目を処理中であることを意味します。レスポンスに details.leaseExpiresAt が含まれるため、その時刻まで待って項目を再読み取りしてから再試行してください。409 WORK_CHANGED は別リクエストがワーク項目を変更したことを意味します。新しいワークを上書きせず現在状態を読み取ってください。

修復操作は { "scope": "collection", "collection": "articles" } または { "scope": "all" } を受け付けます。全コレクション修復は同期的かつ順次実行されるため、大規模サイトでは時間がかかります。200 レスポンスでも partial、failed、stale を報告する場合があります。修復完了とみなす前に data.status、コレクション別状態、ソース件数を確認してください。

サイト転送

/_emdash/api/admin/transfer/ 配下の転送操作は、サイトをサイト パッケージとしてエクスポートし、空のサイトへインポートします。サイト転送ガイド がエクスポート、アップロード、分析、実行、受領のワークフローを説明します。

セッション ユーザーには管理者のみが持つ transfer:export または transfer:import 権限が必要です。Bearer トークンには各操作で指定される admin または transfer:export、transfer:analyze、transfer:execute スコープが必要です。承認操作はサインイン済みセッションのみ受け付けます。MCP の site_export_start と site_import_start ツールが行ったリクエストを決定します。REST の export と execute 操作は承認を要しません。

インポート実行中、および失敗またはキャンセル後に abandon されるまで、ほとんどの他の書き込み操作は 503 TRANSFER_IMPORT_IN_PROGRESS を返します。ガイドに インポート中も利用可能な操作 が一覧されています。

ページネーション

一覧操作は OpenAPI でページネーション パラメーターを説明します。ほとんどのカーソル ページネーション操作は不透明な cursor と 1〜100（既定 50）の limit を受け付けます。前回レスポンスの nextCursor をそのまま返してください。解析または構築しないでください。一部メディア操作は番号付きページにも対応し、一部の専用一覧は異なる上限を使うため、生成クライアントは各操作のスキーマに従うべきです。

検索トークナイザー

検索有効化操作はコレクションごとにトークナイザーを保存します。有効なコレクションで変更すると、そのコレクションのインデックスが再構築されます。

検索無効化は次回有効化のために保存トークナイザーを保持します。再構築操作はコレクションの保存トークナイザーとフィールド重みを使用します。

コメントとリダイレクト

公開コメント送信はモデレーション キューに入ります。管理コメント操作はすべての状態を一覧し、件数を返し、1 件の状態を更新し、一括モデレーションを行い、コメントを完全削除します。429 レスポンスは送信レート制限に達したことを意味します。

リダイレクト操作はリダイレクト規則と記録 404 ログを別々に管理します。整理（prune）はリクエスト ボディで選択したエントリーを削除し、DELETE /redirects/404s はログ全体を消去します。いずれもリダイレクト規則は削除しません。