Skip to content

0019. One action registry with `api` and `endpoint` kinds

  • Status: Accepted
  • Date: 2026-11-08

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.

  • Every operation is declared once with defineAction in core/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, and llms.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 endpoint action uses API-key, OAuth, or session auth, so a user-facing action cannot avoid parity.
  • The dashboard and MCP call only api actions.
  • Handlers receive the verified ProjectScope and call ProjectExecutor; 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.

  • 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-action skill 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.