API ルート

プラグインは管理 UI や外部連携のための API ルートを公開できます。ルートは /_emdash/api/plugins/<slug>/<ルート名> にマウントされ、フックが受け取るのと同じ PluginContext でサンドボックスランタイム内で実行されます。

このページはサンドボックスプラグインを対象としています。ネイティブプラグインの API サーフェスは同一で、ハンドラーシグネチャのみが異なります — ネイティブプラグインを参照してください。

ルートの定義

サンドボックスルートハンドラーは 2つの引数を取ります: (routeCtx, ctx)。

インデックス付きコンテンツフィールドのフィルタリング

ルート URL

認証と CSRF

プラグインルートはデフォルトで認証されます。 パブリックルートには public: true を使用します。

認証済み呼び出し元

プライベートルートでは routeCtx.user は認証されたユーザーです。

ルートを MCP ツールとして公開

入力バリデーション

input は Zod スキーマを受け付けます。

戻り値

JSON シリアライズ可能な値を返します。

エラー

エラーレスポンスにはスローします。

HTTP メソッド

ルートはすべてのメソッドに応答します。routeCtx.request.method で分岐します。

一般的なパターン

KV による設定

ページネーション付きリスト

外部 API プロキシ

管理 UI からルートを呼び出す

import { usePluginAPI } from "@emdash-cms/admin";

キューおよびスケジュールハンドラーからルートを呼び出す

emdash/middleware の withEmDashRuntime() を使用します。

外部からルートを呼び出す

パブリックルートは直接呼び出せます。プライベートルートにはセッション資格情報または API トークンが必要です。

ルートコンテキストリファレンス

interface SandboxedRouteContext {
	input: unknown;
	request: SandboxedRequest;
	requestMeta?: unknown;
	user?: UserInfo;
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	content?: ContentAccess;
	taxonomies?: TaxonomyAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	users?: UserAccess;
	email?: EmailAccess;
}