docs(connectors): add GET + POST /api/connectors/actions for sandbox tool execution

Merged
SW
6mo ago
+258-1

Summary

Sandbox agents (open-agents) currently can't reach the third-party connector tools (Gmail, Notion, Linear, Sheets, etc.) that the chat agent uses internally — those tools live behind a session-bound layer in api/lib/chat/setupToolsForRequest.ts that's not reachable from a sandbox curl.

This is PR 1 of 3 in the connector-actions rollout — the contract. Doc-driven: PR 1 lands the spec, PR 2 implements api/ against it, PR 3 updates the recoup-api skill to point sandbox agents at the new endpoints.

The new endpoints slot under the existing Connectors abstraction. Composio is not named in public docs — same as the existing /api/connectors family. The engine behind connectors stays swappable.

Endpoints

EndpointPurpose
GET /api/connectors/actionsList executable actions across the authenticated account's connectors. Each action returns slug (UPPERCASE_SNAKE_CASE, e.g. GITHUB_CREATE_ISSUE), name, description, parameters (JSON Schema), connectorSlug (parent toolkit), isConnected. Optional account_id query param mirrors the existing GET /api/connectors pattern.
POST /api/connectors/actionsExecute an action by slug with parameters. Body: { actionSlug, parameters, account_id? }. Response: { success, result, executedAt }. The wrapper validates against the cached action schema and checks connection state before invoking.

Error codes

  • 401 — missing / invalid auth.
  • 403 — token valid but no access to the specified account_id.
  • 404 — actionSlug doesn't exist in any of the account's connectors.
  • 409 — the action's parent connector isn't connected; client should call POST /api/connectors to authorize first.
  • 502 — upstream third-party service errored or timed out.
  • 400 — parameters doesn't match the action's schema (or actionSlug missing).

All error responses reuse the existing Error schema ({ error: int, message: string }).

Files changed

  • api-reference/openapi/social.json — added 2 new paths and 4 new schemas (ConnectorAction, ConnectorActionsResponse, ExecuteConnectorActionRequest, ExecuteConnectorActionResponse).
  • api-reference/connectors/list-actions.mdx — new, frontmatter-only.
  • api-reference/connectors/execute-action.mdx — new, frontmatter-only.
  • docs.json — both pages added to the existing Connectors group.

Design decisions, briefly

  • Single path with multiple verbs for the new endpoints (mirrors the existing /api/connectors style: GET=list, POST=execute) — keeps the OpenAPI section compact.
  • Slug format documented as UPPERCASE_SNAKE_CASE in the field description so callers don't trip over the case (verified against Composio's own docs without naming Composio).
  • parameters not arguments — wrapper-side naming consistent with our other connector endpoints; description notes that the connector validates the shape before invoking.
  • Auth pattern reuses validateAuthContext + RECOUP_ACCESS_TOKEN — same path the existing /api/connectors family uses, so no new auth surface in PR 2.

Test plan

  • Preview locally via npx mintlify@latest dev — verify the two new pages render with correct request/response schemas + status code descriptions
  • Check the Connectors group in nav has all 5 entries in the right order (list, authorize, disconnect, list-actions, execute-action)
  • Verify all $ref schemas resolve in social.json (jq -e validates JSON parses; Mintlify will catch schema-resolution issues)

Order of merge

  1. This PR (docs) — contract.
  2. api PR (TBD) — app/api/connectors/actions/route.ts implementation against this spec; reuses validateAuthContext and the existing Composio integration in lib/composio/.
  3. skills PR (TBD) — recoup-api/SKILL.md adds a "Connector actions" section pointing at these merged docs URLs.

🤖 Generated with Claude Code

Summary by cubic

Adds GET and POST /api/connectors/actions so sandbox agents can list and run connector tools over HTTP. This PR documents the contract (OpenAPI + docs); implementation follows in a separate PR.

  • New Features
    • GET /api/connectors/actions — lists actions across connectors; returns slug (UPPERCASE_SNAKE_CASE), name, description, parameters (JSON Schema), connectorSlug, isConnected; supports optional account_id.
    • POST /api/connectors/actions — executes an action by actionSlug with parameters (and optional account_id); responds with { success, result, executedAt }; validates schema and connection; errors: 400/401/403/404/409/502 using existing Error schema.
    • OpenAPI: added paths and schemas ConnectorAction, ConnectorActionsResponse, ExecuteConnectorActionRequest, ExecuteConnectorActionResponse.
    • Docs: added api-reference/connectors/list-actions.mdx and api-reference/connectors/execute-action.mdx; linked in docs.json under Connectors.

Summary by CodeRabbit

  • Documentation

    • Added API reference pages for "Execute Connector Action" and "List Connector Actions"
    • Updated navigation to include new connector action documentation

  • New Features

    • Introduced endpoints to list available connector actions across accessible connectors
    • Introduced endpoint to execute connector actions with support for action-specific parameters and cross-account execution