0019. One action registry with `api` and `endpoint` kinds
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”ADR 0005 requires every action to exist in REST, MCP, OpenAPI, and the docs with identical inputs, validation, and errors. Some HTTP routes are not user actions: inbound webhooks, provider webhooks, unsubscribe links, and click redirects are called by machines or mail recipients with their own verification, and have no MCP equivalent.
Decision
Section titled “Decision”- Every operation is declared once with
defineActionincore/actions/: name (resource.verb), HTTP method and path, zod input and output schemas, auth strategy, required scope and role, stable error codes, MCP annotations, and handler. kind: "api"actions are generated into REST routes, OpenAPI, MCP tools, the docs index, andllms.txt, and are covered by the parity test.kind: "endpoint"actions are HTTP-only endpoints with their own verification (inbound webhook, SES event receiver, unsubscribe, click redirect). They share validation, scope minting, and the isolation fixture (two workspaces; the first has two projects).- The parity test fails if an
endpointaction uses API-key, OAuth, or session auth, so a user-facing action cannot avoid parity. - The dashboard and MCP call only
apiactions. - Handlers receive the verified
ProjectScopeand callProjectExecutor; they never take a project ID from input.
Amendment (2026-11-19, ADR 0041): the auth strategy auth: "api_key" becomes principal (project_key, user, or any), and an action also declares its target (project, workspace, or actor) and the least role (admin or member). workspace handlers receive a WorkspaceScope and actor handlers an ActorScope; neither takes a tenant ID from input.
Consequences
Section titled “Consequences”- The isolation fixture is generated from the registry, so new actions are covered automatically: calling an action as one project with the IDs of another project, in the same workspace or another workspace, returns not found.
- The
add-api-actionskill follows this registry.
Amendment (2026-11-19, pending ADR 0050, Proposed): an action that can start sends declares startsSends: true and previewSends; defineApiAction derives its confirmation input, its output union (confirmation_required, confirmation_pending, done), and the error code confirmation_invalid, and invokeApiAction consumes the token in the commit’s project-store transaction.