Rotas de API

Plugins podem expor rotas de API para sua UI admin e integrações externas. As rotas são montadas em /_emdash/api/plugins/<slug>/<nome-rota> e executam dentro do runtime sandbox com o mesmo PluginContext que os hooks recebem.

Esta página cobre plugins sandboxed. A superfície de API para plugins nativos é idêntica; a única diferença é a assinatura do handler — veja Plugins nativos.

Definir rotas

Handlers de rotas sandboxed recebem dois argumentos: (routeCtx, ctx).

Filtrar campos de conteúdo indexados

URLs de rotas

Autenticação e CSRF

Rotas de plugin são autenticadas por padrão. Use public: true para rotas públicas.

O chamador autenticado

Em rotas privadas, routeCtx.user é o usuário autenticado.

Expor uma rota como ferramenta MCP

Validação de entrada

input aceita um schema Zod.

Valores de retorno

Retorne qualquer valor serializável em JSON.

Erros

Lance um erro para uma resposta de erro.

Métodos HTTP

Rotas respondem a todos os métodos. Ramifique em routeCtx.request.method.

Padrões comuns

Configurações via KV

Lista paginada

Proxy de API externa

Chamar rotas da UI admin

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

Chamar rotas de handlers de fila e agendados

Use withEmDashRuntime() de emdash/middleware.

Chamar rotas externamente

Rotas públicas são chamáveis diretamente. Rotas privadas precisam de credenciais de sessão ou token API.

Referência do contexto de rota

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;
}