Document Action Gateway data plane REST APIs

[tgillam-do]

Summary

Adds an Action Gateway Data Plane tag that documents the gateway's REST endpoints, which are the REST forms of a session's MCP meta tools (action_search, action_invoke, action_code). These operations use their own base URL, https://actions.do-ai.run, set per operation in servers, the same way the Inference endpoints use https://inference.do-ai.run.

Operation	Endpoint
gatewayTools_list	GET /tools
gatewayTools_list_search	POST /tools/search
gatewayTools_run	POST /tools/invoke
gatewayCode_run	POST /code/execute
gatewaySessionApprovals_update	POST /approvals/session/{session_id}/{approval_id}
gatewayApprovals_update	POST /approvals/{approval_id} (session in X-Session-Id)

MCP routes and the tool registry APIs are out of scope.

What's documented

• Auth and sessions: a DigitalOcean token as a Bearer token, which needs the action_gateway:execute scope, plus a session UUID in X-Session-Id or in the path. The session must belong to the same user and team. When the team is not enabled, requests return a 412 release gate.
• Results and errors: gateway responses, including errors, use the ToolResult envelope (status, output, error{class, message, retriable, recovery_hint}, call_id, _meta). Status codes and messages follow the gateway's sanitized error registry. Edge rejections (401, and 403 for scope or account standing) use the standard DigitalOcean error format. Request bodies are limited to 1 MiB.
• Approvals: calls gated by an ask policy return _meta.status: requires_approval with approval_id, expires_at, and a decide request description.
• Request limits:
  • Search accepts 1 to 5 queries. Each use_case can be up to 512 bytes and 32 search terms and must contain at least one letter or digit. limit defaults to 10 and is capped at 50.
  • Invoke accepts 1 to 10 calls.
  • GET /tools pages 1 to 100 tools (default 20) using a session-pinned page token, with ETag and If-None-Match returning 304.
• The Action Gateway tag description now links to the data plane tag, and the new tag is added to x-tagGroups under Public APIs.

Lint rule changes (spectral/ruleset.yml)

• path-must-include-version now allows the unversioned data plane paths.
• ratelimit-headers skips those same paths. Edge's actions-api route for these endpoints has no rate-limiter filter, and the gateway doesn't set ratelimit-* headers, so documenting them would be wrong. Retry-After is documented on 429 because the gateway sets it when a tool-call limit is hit. I confirmed the rule still fails a /v2 response that lacks the headers.

Verification

Checked against cthulhu origin/master (5d665672, Oct 15) and action-infra-manifest main (82d9b4a8):

• Routes: the gateway's server.go and Edge's extauth/actions-api.jsonnet list the same six paths.
• Scope: the Edge route requires permissions.action_gateway_execute, which is action_gateway:execute.
• Errors: the error enums, the HTTP status, message, and recovery hint for each code, and the GET /tools paging behavior match the gateway code.
• Lint: make lint passes with 0 errors. All 8 warnings were already on main, and none are in action_gateway files.
• Rendering: the Product Docs generator renders the page with scope pills and the 403 oneOf.

Not verified

No calls were made against actions.do-ai.run with a real token; response bodies come from the gateway source.

Follow-up

A separate Product Docs PR will:

• map action-gateway and action-gateway-data-plane in scripts/product-stubs.yaml
• add the MCP reference page
• group the Action Gateway reference pages in the navigation

[anup-deka]

LGTM