diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index b8c29b46..afdfe92f 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -60,6 +60,11 @@ tags: The Add-Ons API allows you to manage these resources, including creating, listing, and retrieving details about specific add-on resources. + - name: Action Gateway + description: |- + Discover Action Gateway tools and providers, manage versioned toolbelts and + OAuth connections, and create policy-bound sessions for end users. + - name: Apps description: |- App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows @@ -662,6 +667,7 @@ x-tagGroups: - Account - Actions - Add-Ons + - Action Gateway - Apps - Billing - Block Storage @@ -718,6 +724,74 @@ x-tagGroups: - Serverless Inference paths: + /v2/action-gateway/tools: + get: + $ref: "resources/action_gateway/tools_list.yml" + + /v2/action-gateway/tools/toolkits: + get: + $ref: "resources/action_gateway/tools_list_toolkits.yml" + + /v2/action-gateway/tools/providers: + get: + $ref: "resources/action_gateway/tools_list_providers.yml" + + /v2/action-gateway/tools/{name}/definition: + get: + $ref: "resources/action_gateway/tools_get_definition.yml" + + /v2/action-gateway/toolbelts: + get: + $ref: "resources/action_gateway/toolbelts_list.yml" + post: + $ref: "resources/action_gateway/toolbelts_create.yml" + + /v2/action-gateway/toolbelts/{name}: + get: + $ref: "resources/action_gateway/toolbelts_get.yml" + delete: + $ref: "resources/action_gateway/toolbelts_delete.yml" + + /v2/action-gateway/toolbelts/{name}/tools/add: + post: + $ref: "resources/action_gateway/toolbelts_add_tools.yml" + + /v2/action-gateway/toolbelts/{name}/tools/remove: + post: + $ref: "resources/action_gateway/toolbelts_remove_tools.yml" + + /v2/action-gateway/connections: + get: + $ref: "resources/action_gateway/connections_list.yml" + post: + $ref: "resources/action_gateway/connections_create.yml" + + /v2/action-gateway/connections/{id}: + get: + $ref: "resources/action_gateway/connections_get.yml" + patch: + $ref: "resources/action_gateway/connections_update.yml" + delete: + $ref: "resources/action_gateway/connections_delete.yml" + + /v2/action-gateway/users: + get: + $ref: "resources/action_gateway/users_list.yml" + + /v2/action-gateway/users/{user_id}: + get: + $ref: "resources/action_gateway/users_get.yml" + + /v2/action-gateway/sessions: + get: + $ref: "resources/action_gateway/sessions_list.yml" + post: + $ref: "resources/action_gateway/sessions_create.yml" + + /v2/action-gateway/sessions/{session_urn}: + delete: + $ref: "resources/action_gateway/sessions_delete.yml" + /v2/1-clicks: get: $ref: "resources/1-clicks/oneClicks_list.yml" diff --git a/specification/resources/action_gateway/connections_create.yml b/specification/resources/action_gateway/connections_create.yml new file mode 100644 index 00000000..0b4267fb --- /dev/null +++ b/specification/resources/action_gateway/connections_create.yml @@ -0,0 +1,44 @@ +operationId: connections_create +summary: Create a Connection +description: Creates or begins authorization for an OAuth connection to an + Action Gateway provider. +tags: + - Action Gateway +requestBody: + required: true + content: + application/json: + schema: + $ref: models.yml#/create_connection_request + examples: + connections_create_request: + $ref: examples.yml#/connections_create_request +responses: + "200": + description: The connection was created or authorization was started. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/create_connection_response + examples: + connections_create_response: + $ref: examples.yml#/connections_create_response + "400": + $ref: ../../shared/responses/bad_request.yml + "401": + $ref: ../../shared/responses/unauthorized.yml + "409": + $ref: ../../shared/responses/conflict.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:create +x-codeSamples: + - $ref: examples/curl/connections_create.yml diff --git a/specification/resources/action_gateway/connections_delete.yml b/specification/resources/action_gateway/connections_delete.yml new file mode 100644 index 00000000..327df8b0 --- /dev/null +++ b/specification/resources/action_gateway/connections_delete.yml @@ -0,0 +1,40 @@ +operationId: connections_delete +summary: Delete a Connection +description: Revokes and deletes an OAuth connection owned by the authenticated team. +tags: + - Action Gateway +parameters: + - name: id + in: path + required: true + description: The connection UUID. + schema: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 +responses: + "200": + description: The connection was deleted successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/delete_connection_response + examples: + connections_delete_response: + $ref: examples.yml#/connections_delete_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:delete +x-codeSamples: + - $ref: examples/curl/connections_delete.yml diff --git a/specification/resources/action_gateway/connections_get.yml b/specification/resources/action_gateway/connections_get.yml new file mode 100644 index 00000000..efab01b7 --- /dev/null +++ b/specification/resources/action_gateway/connections_get.yml @@ -0,0 +1,40 @@ +operationId: connections_get +summary: Retrieve a Connection +description: Retrieves an OAuth connection owned by the authenticated team. +tags: + - Action Gateway +parameters: + - name: id + in: path + required: true + description: The connection UUID. + schema: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 +responses: + "200": + description: The connection was retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/get_connection_response + examples: + connections_get_response: + $ref: examples.yml#/connections_get_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/connections_get.yml diff --git a/specification/resources/action_gateway/connections_list.yml b/specification/resources/action_gateway/connections_list.yml new file mode 100644 index 00000000..f51f36c8 --- /dev/null +++ b/specification/resources/action_gateway/connections_list.yml @@ -0,0 +1,63 @@ +operationId: connections_list +summary: List Connections +description: Lists OAuth connections owned by the authenticated team. +tags: + - Action Gateway +parameters: + - name: provider + in: query + description: Filter by provider name. + schema: + type: string + example: github + - name: user_id + in: query + description: Filter by end-user identifier. + schema: + type: string + example: end-user-123 + - name: status + in: query + description: Filter by connection status. + schema: + type: string + example: active + - name: sort + in: query + description: Field used to sort results. + schema: + type: string + example: created_at + - name: sort_direction + in: query + description: Sort direction. + schema: + type: string + example: desc + - $ref: ../../shared/parameters.yml#/page + - $ref: ../../shared/parameters.yml#/per_page +responses: + "200": + description: Connections were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_connections_response + examples: + connections_list_response: + $ref: examples.yml#/connections_list_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/connections_list.yml diff --git a/specification/resources/action_gateway/connections_update.yml b/specification/resources/action_gateway/connections_update.yml new file mode 100644 index 00000000..6d4145e2 --- /dev/null +++ b/specification/resources/action_gateway/connections_update.yml @@ -0,0 +1,51 @@ +operationId: connections_update +summary: Update Connection Parameters +description: Updates non-sensitive connection parameters for an OAuth connection. +tags: + - Action Gateway +parameters: + - name: id + in: path + required: true + description: The connection UUID. + schema: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 +requestBody: + required: true + content: + application/json: + schema: + $ref: models.yml#/update_connection_parameters_request + examples: + connections_update_request: + $ref: examples.yml#/connections_update_request +responses: + "200": + description: The connection parameters were updated successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/update_connection_parameters_response + examples: + connections_update_response: + $ref: examples.yml#/connections_update_response + "400": + $ref: ../../shared/responses/bad_request.yml + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:update +x-codeSamples: + - $ref: examples/curl/connections_update.yml diff --git a/specification/resources/action_gateway/examples.yml b/specification/resources/action_gateway/examples.yml new file mode 100644 index 00000000..ec214939 --- /dev/null +++ b/specification/resources/action_gateway/examples.yml @@ -0,0 +1,342 @@ +tools_list_response: + value: + version: v1 + tools: + - name: exa_web_search + toolkitId: exa + title: Search the Web + description: Search public web pages. + inputSchema: + type: object + properties: + query: + type: string + annotations: + title: Search the Web + readOnlyHint: true + idempotentHint: true + openWorldHint: true + destructiveHint: false + version: v1 + parallelizable: true + streamingSafe: false + outputSchema: + type: object + toolSlug: exa_web_search + definitions: [] + pagination: + page: 1 + per_page: 20 + total: 1 + +tools_list_toolkits_response: + value: + version: v1 + toolkits: + - id: 123e4567-e89b-12d3-a456-426614174000 + name: exa + description: Web search and content retrieval tools. + +tools_list_providers_response: + value: + providers: + - name: github + display_name: GitHub + description: Connect Action Gateway to GitHub. + auth_type: oauth2 + scopes: + - repo + connection_parameters: [] + +tools_get_definition_response: + value: + toolId: tool-123 + name: exa_web_search + toolkitId: exa + title: Search the Web + description: Search public web pages. + inputSchema: + type: object + properties: + query: + type: string + required: + - query + outputSchema: + type: object + annotations: + title: Search the Web + readOnlyHint: true + idempotentHint: true + openWorldHint: true + destructiveHint: false + version: v1 + schemaVersion: "1" + status: active + parallelizable: true + streamingSafe: false + tags: + - search + toolSlug: exa_web_search + +toolbelts_create_request: + value: + name: search-toolbelt + display_name: Search Tools + description: Tools for searching and fetching public web pages. + tools: + - exa_web_search + - exa_web_fetch + +toolbelt_response: + value: + toolbelt: + name: search-toolbelt + version: "1" + display_name: Search Tools + description: Tools for searching and fetching public web pages. + tools: + - exa_web_search + - exa_web_fetch + status: active + reference: search-toolbelt@1 + reference_latest: search-toolbelt + tool_count: 2 + created_at: 2026-06-11T12:00:00Z + updated_at: 2026-06-11T12:00:00Z + +toolbelts_delete_response: + value: + toolbelt: + name: search-toolbelt + version: "1" + display_name: Search Tools + description: Tools for searching and fetching public web pages. + tools: + - exa_web_search + - exa_web_fetch + status: deprecated + reference: search-toolbelt@1 + reference_latest: search-toolbelt + tool_count: 2 + created_at: 2026-06-11T12:00:00Z + updated_at: 2026-06-11T13:00:00Z + +toolbelts_list_response: + value: + toolbelts: + - name: search-toolbelt + display_name: Search Tools + description: Tools for searching and fetching public web pages. + latest_version: "1" + version_count: 1 + tool_count: 2 + status: active + reference_latest: search-toolbelt + updated_at: 2026-06-11T12:00:00Z + pagination: + page: 1 + per_page: 20 + total: 1 + +toolbelts_add_tools_request: + value: + tools: + - exa_web_fetch + +toolbelts_remove_tools_request: + value: + tools: + - exa_web_fetch + +connections_create_request: + value: + provider: github + user_id: end-user-123 + scopes: + - repo + connection_parameters: {} + +connections_create_response: + value: + connection: + id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: pending + created_at: 2026-06-11T12:00:00Z + provider_display_name: GitHub + connection_parameters: {} + authorization: + status: pending + connect_url: https://cloud.digitalocean.com/action-gateway/connections/connect + verification_code: ABCD-EFGH + expires_at: 2026-06-11T12:15:00Z + +connections_list_response: + value: + connections: + - id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: active + created_at: 2026-06-11T12:00:00Z + granted_at: 2026-06-11T12:01:00Z + provider_display_name: GitHub + connection_parameters: {} + pagination: + page: 1 + per_page: 20 + total: 1 + +connections_get_response: + value: + connection: + id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: active + created_at: 2026-06-11T12:00:00Z + granted_at: 2026-06-11T12:01:00Z + provider_display_name: GitHub + connection_parameters: {} + +connections_update_request: + value: + connection_parameters: + site_url: https://github.com + +connections_update_response: + value: + connection: + id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: active + created_at: 2026-06-11T12:00:00Z + granted_at: 2026-06-11T12:01:00Z + provider_display_name: GitHub + connection_parameters: + site_url: https://github.com + +connections_delete_response: + value: + connection: + id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: revoked + created_at: 2026-06-11T12:00:00Z + granted_at: 2026-06-11T12:01:00Z + revoked_at: 2026-06-11T13:00:00Z + provider_display_name: GitHub + connection_parameters: {} + +users_list_response: + value: + user_ids: + - end-user-123 + pagination: + page: 1 + per_page: 20 + total: 1 + +users_get_response: + value: + user: + user_id: end-user-123 + sessions: + - session_urn: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 + name: research-session + created_at: 2026-06-11T12:00:00Z + updated_at: 2026-06-11T12:00:00Z + connections: + - id: 123e4567-e89b-12d3-a456-426614174000 + provider: github + user_id: end-user-123 + scopes: + - repo + status: active + created_at: 2026-06-11T12:00:00Z + granted_at: 2026-06-11T12:01:00Z + provider_display_name: GitHub + connection_parameters: {} + +sessions_create_request: + value: + name: research-session + actor_id: end-user-123 + policy: + defaultAction: ask + rules: + - tool: exa_web_search + action: allow + tools: + - exa_web_search@v1 + config: + preloadTools: + - exa_web_search@v1 + +sessions_create_response: + value: + session: + sessionUrn: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 + policy: + defaultAction: ask + rules: + - tool: exa_web_search + action: allow + createdAt: 2026-06-11T12:00:00Z + updatedAt: 2026-06-11T12:00:00Z + name: research-session + actorId: end-user-123 + tools: + references: + - kind: SESSION_TOOL_REFERENCE_KIND_TOOL + name: exa_web_search + version: v1 + config: + preloadTools: + - exa_web_search@v1 + mcpUrl: https://actions.do-ai.run/mcp/session/123e4567-e89b-12d3-a456-426614174000 + tools: + - exa_web_search@v1 + +sessions_list_response: + value: + sessions: + - sessionUrn: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 + policy: + defaultAction: ask + rules: + - tool: exa_web_search + action: allow + createdAt: 2026-06-11T12:00:00Z + updatedAt: 2026-06-11T12:00:00Z + name: research-session + actorId: end-user-123 + tools: + references: + - kind: SESSION_TOOL_REFERENCE_KIND_TOOL + name: exa_web_search + version: v1 + config: + preloadTools: + - exa_web_search@v1 + pagination: + page: 1 + per_page: 20 + total: 1 + +sessions_delete_response: + value: {} diff --git a/specification/resources/action_gateway/examples/curl/connections_create.yml b/specification/resources/action_gateway/examples/curl/connections_create.yml new file mode 100644 index 00000000..09793881 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/connections_create.yml @@ -0,0 +1,12 @@ +lang: cURL +source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "provider": "github", + "user_id": "end-user-123", + "scopes": ["repo"], + "connection_parameters": {} + }' \ + "https://api.digitalocean.com/v2/action-gateway/connections" diff --git a/specification/resources/action_gateway/examples/curl/connections_delete.yml b/specification/resources/action_gateway/examples/curl/connections_delete.yml new file mode 100644 index 00000000..95afd9b3 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/connections_delete.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/connections/123e4567-e89b-12d3-a456-426614174000" diff --git a/specification/resources/action_gateway/examples/curl/connections_get.yml b/specification/resources/action_gateway/examples/curl/connections_get.yml new file mode 100644 index 00000000..ff51c350 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/connections_get.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/connections/123e4567-e89b-12d3-a456-426614174000" diff --git a/specification/resources/action_gateway/examples/curl/connections_list.yml b/specification/resources/action_gateway/examples/curl/connections_list.yml new file mode 100644 index 00000000..497fa188 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/connections_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/connections?user_id=end-user-123" diff --git a/specification/resources/action_gateway/examples/curl/connections_update.yml b/specification/resources/action_gateway/examples/curl/connections_update.yml new file mode 100644 index 00000000..7fd18f0d --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/connections_update.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"connection_parameters": {"site_url": "https://github.com"}}' \ + "https://api.digitalocean.com/v2/action-gateway/connections/123e4567-e89b-12d3-a456-426614174000" diff --git a/specification/resources/action_gateway/examples/curl/sessions_create.yml b/specification/resources/action_gateway/examples/curl/sessions_create.yml new file mode 100644 index 00000000..ccaf8445 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/sessions_create.yml @@ -0,0 +1,16 @@ +lang: cURL +source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "research-session", + "actor_id": "end-user-123", + "policy": { + "defaultAction": "ask", + "rules": [{"tool": "exa_web_search", "action": "allow"}] + }, + "tools": ["exa_web_search@v1"], + "config": {"preloadTools": ["exa_web_search@v1"]} + }' \ + "https://api.digitalocean.com/v2/action-gateway/sessions" diff --git a/specification/resources/action_gateway/examples/curl/sessions_delete.yml b/specification/resources/action_gateway/examples/curl/sessions_delete.yml new file mode 100644 index 00000000..ca872e4d --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/sessions_delete.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/sessions/do%3Amanaged_agents_session%3A123e4567-e89b-12d3-a456-426614174000" diff --git a/specification/resources/action_gateway/examples/curl/sessions_list.yml b/specification/resources/action_gateway/examples/curl/sessions_list.yml new file mode 100644 index 00000000..8a61e28c --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/sessions_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/sessions?end_user_id=end-user-123" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_add_tools.yml b/specification/resources/action_gateway/examples/curl/toolbelts_add_tools.yml new file mode 100644 index 00000000..8aa7827d --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_add_tools.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tools": ["exa_web_fetch"]}' \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts/search-toolbelt/tools/add" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_create.yml b/specification/resources/action_gateway/examples/curl/toolbelts_create.yml new file mode 100644 index 00000000..063258fd --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_create.yml @@ -0,0 +1,11 @@ +lang: cURL +source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "search-toolbelt", + "display_name": "Search Tools", + "tools": ["exa_web_search", "exa_web_fetch"] + }' \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_delete.yml b/specification/resources/action_gateway/examples/curl/toolbelts_delete.yml new file mode 100644 index 00000000..5af558fb --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_delete.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts/search-toolbelt" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_delete_tools.yml b/specification/resources/action_gateway/examples/curl/toolbelts_delete_tools.yml new file mode 100644 index 00000000..da106035 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_delete_tools.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tools": ["exa_web_fetch"]}' \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts/search-toolbelt/tools/remove" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_get.yml b/specification/resources/action_gateway/examples/curl/toolbelts_get.yml new file mode 100644 index 00000000..f1665f49 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_get.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts/search-toolbelt?version=1" diff --git a/specification/resources/action_gateway/examples/curl/toolbelts_list.yml b/specification/resources/action_gateway/examples/curl/toolbelts_list.yml new file mode 100644 index 00000000..ff52861f --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/toolbelts_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/toolbelts?status=active" diff --git a/specification/resources/action_gateway/examples/curl/tools_get_definition.yml b/specification/resources/action_gateway/examples/curl/tools_get_definition.yml new file mode 100644 index 00000000..b24b5d11 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/tools_get_definition.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/tools/exa_web_search/definition?version=v1" diff --git a/specification/resources/action_gateway/examples/curl/tools_list.yml b/specification/resources/action_gateway/examples/curl/tools_list.yml new file mode 100644 index 00000000..1e61b208 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/tools_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/tools?toolkit_id=exa" diff --git a/specification/resources/action_gateway/examples/curl/tools_list_providers.yml b/specification/resources/action_gateway/examples/curl/tools_list_providers.yml new file mode 100644 index 00000000..9bb8a42c --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/tools_list_providers.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/tools/providers" diff --git a/specification/resources/action_gateway/examples/curl/tools_list_toolkits.yml b/specification/resources/action_gateway/examples/curl/tools_list_toolkits.yml new file mode 100644 index 00000000..8444f4db --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/tools_list_toolkits.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/tools/toolkits" diff --git a/specification/resources/action_gateway/examples/curl/users_get.yml b/specification/resources/action_gateway/examples/curl/users_get.yml new file mode 100644 index 00000000..cf96ab54 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/users_get.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/users/end-user-123" diff --git a/specification/resources/action_gateway/examples/curl/users_list.yml b/specification/resources/action_gateway/examples/curl/users_list.yml new file mode 100644 index 00000000..ecd383d6 --- /dev/null +++ b/specification/resources/action_gateway/examples/curl/users_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/action-gateway/users" diff --git a/specification/resources/action_gateway/models.yml b/specification/resources/action_gateway/models.yml new file mode 100644 index 00000000..813e9651 --- /dev/null +++ b/specification/resources/action_gateway/models.yml @@ -0,0 +1,1151 @@ +toolbelt: + type: object + required: + - name + - version + - tools + - status + - reference + - reference_latest + - tool_count + - created_at + - updated_at + properties: + name: + type: string + example: search-toolbelt + version: + type: string + pattern: ^[0-9]+$ + example: "1" + display_name: + type: string + maxLength: 128 + example: Search Tools + description: + type: string + maxLength: 255 + example: Tools for searching and fetching public web pages. + tools: + type: array + maxItems: 500 + items: + type: string + example: + - exa_web_search + - exa_web_fetch + status: + type: string + enum: + - active + - deprecated + example: active + reference: + type: string + description: A reference pinned to this immutable toolbelt version. + example: search-toolbelt@1 + reference_latest: + type: string + description: An unversioned reference to the latest active version. + example: search-toolbelt + tool_count: + type: integer + format: int32 + example: 2 + created_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + updated_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + additionalProperties: false +toolbelt_summary: + type: object + required: + - name + - latest_version + - version_count + - tool_count + - status + - reference_latest + - updated_at + properties: + name: + type: string + example: search-toolbelt + display_name: + type: string + example: Search Tools + description: + type: string + example: Tools for searching and fetching public web pages. + latest_version: + type: string + example: "1" + version_count: + type: integer + format: int32 + example: 1 + tool_count: + type: integer + format: int32 + example: 2 + status: + type: string + enum: + - active + - deprecated + example: active + reference_latest: + type: string + example: search-toolbelt + updated_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + additionalProperties: false +toolbelt_create: + type: object + required: + - name + - tools + properties: + name: + type: string + pattern: ^[a-z][a-z0-9_-]{0,63}$ + example: search-toolbelt + version: + type: string + pattern: ^[0-9]+$ + default: "1" + example: "1" + display_name: + type: string + maxLength: 128 + example: Search Tools + description: + type: string + maxLength: 255 + example: Tools for searching and fetching public web pages. + tools: + type: array + maxItems: 500 + items: + type: string + example: + - exa_web_search + - exa_web_fetch + additionalProperties: false +toolbelt_tools: + type: object + required: + - tools + properties: + tools: + type: array + minItems: 1 + maxItems: 500 + items: + type: string + example: + - exa_web_search + additionalProperties: false +toolbelt_response: + type: object + required: + - toolbelt + properties: + toolbelt: + $ref: "#/toolbelt" + additionalProperties: false +toolbelts_response: + type: object + required: + - toolbelts + - pagination + properties: + toolbelts: + type: array + items: + $ref: "#/toolbelt_summary" + example: [] + pagination: + $ref: "#/pagination" + additionalProperties: false +pagination: + type: object + required: + - page + - per_page + - total + properties: + page: + type: integer + format: int32 + example: 1 + per_page: + type: integer + format: int32 + example: 20 + total: + type: integer + format: int32 + example: 1 + additionalProperties: false +auth_injection: + type: object + properties: + location: + type: string + example: header + name: + type: string + example: exa_web_search + scheme: + type: string + example: Bearer + example: + location: header + name: Authorization + scheme: Bearer + additionalProperties: false +auth_spec: + type: object + properties: + modes: + type: array + items: + type: string + example: + - oauth2 + provider: + type: string + example: github + scopes: + type: array + items: + type: string + example: + - repo + credentialBinding: + type: string + example: user + credentialRefSource: + type: string + example: connection + doManagedCredentialRef: + type: string + example: do-managed + injection: + $ref: "#/auth_injection" + baseUrlResolution: + $ref: "#/base_url_resolution" + additionalProperties: false +classification: + type: object + properties: + operation: + type: string + example: search + risk: + type: string + example: low + dataClasses: + type: array + items: + type: string + example: + - public + additionalProperties: false +connection_authorization: + type: object + properties: + status: + type: string + example: active + connect_url: + type: string + example: https://cloud.digitalocean.com/action-gateway/connections/connect + verification_code: + type: string + example: ABCD-EFGH + expires_at: + type: string + format: date-time + example: 2026-06-11T12:15:00Z + description: >- + ConnectionAuthorization is present only while a connection is pending. The + + UI sends the user to connect_url and polls GetConnection until the connection + + becomes active or expires. The Secrets Manager poll URL is never exposed. + additionalProperties: false +connection_parameter_spec: + type: object + properties: + key: + type: string + example: site_url + label: + type: string + example: Site URL + description: + type: string + example: The provider site URL. + input_kind: + type: string + example: url + required: + type: boolean + example: true + normalization: + type: string + example: trim + allowed_values: + type: array + items: + type: string + example: + - option-a + allowed_host_suffixes: + type: array + items: + type: string + example: + - example.com + max_length: + type: integer + format: int32 + example: 255 + description: |- + ConnectionParameterSpec describes one non-sensitive value collected while + configuring a provider connection. The UI and MCP clients render these + specifications generically. + additionalProperties: false +create_connection_request: + type: object + properties: + provider: + type: string + example: github + user_id: + type: string + example: end-user-123 + scopes: + type: array + items: + type: string + example: + - repo + connection_parameters: + type: object + example: + site_url: https://example.com + example: + provider: github + user_id: end-user-123 + scopes: + - repo + connection_parameters: {} + additionalProperties: false +create_connection_response: + type: object + properties: + connection: + $ref: "#/oauth_connection" + authorization: + $ref: "#/connection_authorization" + additionalProperties: false +create_session_request: + type: object + properties: + policy: + allOf: + - $ref: "#/session_policy_spec" + description: Invocation policy. Omit to use a default action of ask. + name: + type: string + example: research-session + tools: + type: array + items: + type: string + description: |- + Omitted enables every tool. An explicit empty array enables no tools. + Direct tools may be or @; toolbelt references must + be version-pinned as toolbelt:@. + example: + - exa_web_search@v1 + config: + type: object + description: >- + Opaque session options. config.preloadTools may contain concrete tool + + names (optionally version-pinned) and version-pinned toolbelt references. + example: {} + properties: + preloadTools: + type: array + items: + type: string + description: Concrete tools or pinned toolbelts to expose directly beside the + session meta-tools. + example: + - exa_web_search@v1 + additionalProperties: true + actor_id: + type: string + example: end-user-123 + example: + name: research-session + actor_id: end-user-123 + policy: + defaultAction: ask + rules: [] + tools: + - exa_web_search@v1 + config: + preloadTools: + - exa_web_search@v1 + additionalProperties: false + required: + - name + - actor_id +create_session_response: + type: object + properties: + session: + $ref: "#/public_session_policy" + mcpUrl: + type: string + description: Public session-pinned MCP URL. + example: https://actions.do-ai.run/mcp/session/123e4567-e89b-12d3-a456-426614174000 + x-client-name: mcpUrl + tools: + type: array + items: + type: string + description: Canonical, version-pinned selected tool references. + example: + - exa_web_search@v1 + additionalProperties: false + required: + - session + - mcpUrl + - tools +delete_connection_response: + type: object + properties: + connection: + $ref: "#/oauth_connection" + additionalProperties: false +delete_session_response: + type: object + example: {} + additionalProperties: false +execution_spec: + type: object + properties: + type: + type: string + example: http + adapterVersion: + type: string + example: v1 + configRef: + type: string + example: exa_web_search@v1 + http: + $ref: "#/http_execution" + mcp: + $ref: "#/mcp_execution" + additionalProperties: false +get_connection_response: + type: object + properties: + connection: + $ref: "#/oauth_connection" + authorization: + $ref: "#/connection_authorization" + additionalProperties: false +get_user_response: + type: object + properties: + user: + $ref: "#/user" + additionalProperties: false +hook_spec: + type: object + properties: + usage: + $ref: "#/usage_spec" + additionalProperties: false +list_connections_response: + type: object + properties: + connections: + type: array + items: + $ref: "#/oauth_connection" + example: [] + pagination: + $ref: "#/pagination" + additionalProperties: false +list_providers_response: + type: object + properties: + providers: + type: array + items: + $ref: "#/provider_summary" + example: [] + additionalProperties: false +list_sessions_response: + type: object + properties: + sessions: + type: array + items: + $ref: "#/public_session_policy" + example: [] + pagination: + $ref: "#/pagination" + additionalProperties: false +list_toolkits_response: + type: object + properties: + version: + type: string + example: v1 + toolkits: + type: array + items: + $ref: "#/toolkit" + example: [] + additionalProperties: false +list_tools_response: + type: object + properties: + version: + type: string + example: v1 + tools: + type: array + items: + $ref: "#/tool" + example: + - name: web_search + definitions: + type: array + items: + $ref: "#/tool_definition" + example: [] + pagination: + $ref: "#/pagination" + additionalProperties: false +list_users_response: + type: object + properties: + user_ids: + type: array + items: + type: string + example: [] + pagination: + $ref: "#/pagination" + additionalProperties: false +oauth_connection: + type: object + properties: + id: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + provider: + type: string + example: github + user_id: + type: string + example: end-user-123 + scopes: + type: array + items: + type: string + example: + - repo + status: + type: string + example: active + granted_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + revoked_at: + type: string + format: date-time + example: 2026-06-12T12:00:00Z + created_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + updated_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + provider_display_name: + type: string + example: GitHub + connection_parameters: + type: object + example: + site_url: https://example.com + description: >- + ----------------------------------------------------------------------------- + + OAuth connection resources + + ----------------------------------------------------------------------------- + + OAuthConnection is the public, team-scoped connection metadata returned to + + the UI. It deliberately excludes the team ID, Secrets Manager assignment, + + actor identifiers, poll URL, and authorization handle. + additionalProperties: false +policy_spec: + type: object + properties: + permission: + type: string + example: read + additionalProperties: false +provider_summary: + type: object + properties: + name: + type: string + example: exa_web_search + display_name: + type: string + example: display_name-example + description: + type: string + example: The provider site URL. + auth_type: + type: string + example: auth_type-example + scopes: + type: array + items: + type: string + example: + - repo + connection_parameters: + type: array + items: + $ref: "#/connection_parameter_spec" + example: [] + additionalProperties: false +public_session_policy: + type: object + properties: + sessionUrn: + type: string + example: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 + x-client-name: sessionUrn + policy: + $ref: "#/session_policy_spec" + createdAt: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + updatedAt: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + name: + type: string + description: name is the required human-readable session name. + example: exa_web_search + actorId: + type: string + description: actor_id is empty when the session is not bound to an actor. + example: end-user-123 + x-client-name: actorId + tools: + allOf: + - $ref: "#/session_tool_selection" + description: |- + Omitted when the request omitted tools (all tools). A present selection + with no references represents tools: []. + config: + type: object + description: |- + Preserved as an opaque object. Gateway currently interprets + config.preloadTools to add selected direct tools to the session MCP. + example: {} + description: A session and the tool-permission policy bound to it. + additionalProperties: false +reliability_spec: + type: object + properties: + timeoutMs: + type: integer + format: int32 + example: 30000 + maxOutputBytes: + type: string + format: int64 + example: "1048576" + retry: + $ref: "#/retry_spec" + additionalProperties: false +retry_spec: + type: object + properties: + maxAttempts: + type: integer + format: int32 + example: 3 + backoff: + type: string + example: exponential + retryOn: + type: array + items: + type: string + example: + - timeout + additionalProperties: false +session_policy_action: + type: string + enum: + - allow + - ask + - deny + default: ask + description: |- + SessionPolicyAction is the disposition applied to a tool call. Lowercase + values are canonical so ProtoJSON matches the public REST vocabulary; the + prefixed aliases preserve compatibility for existing protobuf clients. + example: ask +session_policy_rule: + type: object + properties: + tool: + type: string + example: exa_web_search + match: + type: object + additionalProperties: + type: string + example: + query: DigitalOcean + action: + $ref: "#/session_policy_action" + description: |- + SessionPolicyRule applies an action to a tool or version-pinned toolbelt. + action must be allow, ask, or deny. match optionally narrows the rule to + calls with matching arguments. + additionalProperties: false +session_policy_spec: + type: object + properties: + defaultAction: + $ref: "#/session_policy_action" + rules: + type: array + items: + $ref: "#/session_policy_rule" + example: [] + description: |- + SessionPolicySpec is the Gateway-relevant subset of a session's permission + policy. Filesystem and network policy remain enforced by the sandbox. + additionalProperties: false +session_tool_reference: + type: object + properties: + kind: + $ref: "#/session_tool_reference_kind" + name: + type: string + example: exa_web_search + version: + type: string + example: v1 + additionalProperties: false +session_tool_reference_kind: + type: string + enum: + - SESSION_TOOL_REFERENCE_KIND_TOOL + - SESSION_TOOL_REFERENCE_KIND_TOOLBELT + example: SESSION_TOOL_REFERENCE_KIND_TOOL +session_tool_selection: + type: object + properties: + references: + type: array + items: + $ref: "#/session_tool_reference" + example: + - kind: SESSION_TOOL_REFERENCE_KIND_TOOL + name: exa_web_search + version: v1 + additionalProperties: false +tool: + type: object + properties: + name: + type: string + example: exa_web_search + toolkitId: + type: string + example: exa + title: + type: string + example: Search the Web + description: + type: string + example: The provider site URL. + inputSchema: + type: object + example: + type: object + annotations: + $ref: "#/tool_annotations" + version: + type: string + example: v1 + parallelizable: + type: boolean + example: true + streamingSafe: + type: boolean + example: false + outputSchema: + type: object + example: + type: object + toolSlug: + type: string + description: |- + tool_slug is the provider-qualified, stable tool identifier + "_". Pass this value back verbatim to the toolbelt + add/remove endpoints; clients should treat it as opaque rather than + reconstructing it from toolkit_id and name. + example: exa_web_search + additionalProperties: false +tool_annotations: + type: object + properties: + title: + type: string + example: Search the Web + readOnlyHint: + type: boolean + example: true + idempotentHint: + type: boolean + example: true + openWorldHint: + type: boolean + example: true + destructiveHint: + type: boolean + example: false + additionalProperties: false +tool_definition: + type: object + properties: + toolId: + type: string + example: tool-123 + name: + type: string + example: exa_web_search + toolkitId: + type: string + example: exa + title: + type: string + example: Search the Web + description: + type: string + example: The provider site URL. + inputSchema: + type: object + example: + type: object + outputSchema: + type: object + example: + type: object + annotations: + $ref: "#/tool_annotations" + version: + type: string + example: v1 + schemaVersion: + type: string + example: "1" + status: + type: string + example: active + parallelizable: + type: boolean + example: true + streamingSafe: + type: boolean + example: false + auth: + $ref: "#/auth_spec" + execution: + $ref: "#/execution_spec" + transform: + $ref: "#/transform_spec" + policy: + $ref: "#/policy_spec" + reliability: + $ref: "#/reliability_spec" + hooks: + $ref: "#/hook_spec" + classification: + $ref: "#/classification" + flipperName: + type: string + example: action_gateway_search + tags: + type: array + items: + type: string + example: + - search + toolSlug: + type: string + description: |- + tool_slug is the provider-qualified, stable tool identifier + "_". Pass this value back verbatim to the toolbelt + add/remove endpoints; clients should treat it as opaque. + example: exa_web_search + additionalProperties: false +toolkit: + type: object + properties: + id: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + name: + type: string + example: exa_web_search + description: + type: string + example: The provider site URL. + additionalProperties: false +transform_spec: + type: object + properties: + language: + type: string + example: jq + input: + type: object + example: {} + output: + type: object + example: {} + additionalProperties: false +update_connection_parameters_request: + type: object + properties: + id: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + connection_parameters: + type: object + example: + site_url: https://example.com + additionalProperties: false +update_connection_parameters_response: + type: object + properties: + connection: + $ref: "#/oauth_connection" + additionalProperties: false +usage_meter: + type: object + properties: + sku: + type: string + example: action-gateway-invocation + unit: + type: string + example: request + quantitySource: + type: string + example: invocation_count + additionalProperties: false +usage_spec: + type: object + properties: + billable: + type: boolean + description: |- + When usage metadata is present, false prevents billing. Omitting usage + metadata leaves consumers' legacy billing classification unchanged. + example: true + meters: + type: array + items: + $ref: "#/usage_meter" + example: [] + additionalProperties: false +user: + type: object + properties: + user_id: + type: string + example: end-user-123 + sessions: + type: array + items: + $ref: "#/user_session" + example: [] + connections: + type: array + items: + $ref: "#/oauth_connection" + example: [] + description: User is a derived, team-scoped view across sessions and OAuth connections. + additionalProperties: false +user_session: + type: object + properties: + session_urn: + type: string + example: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 + name: + type: string + example: exa_web_search + created_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + updated_at: + type: string + format: date-time + example: 2026-06-11T12:00:00Z + additionalProperties: false +base_url_resolution: + type: object + properties: + httpLookup: + $ref: "#/http_lookup_spec" + description: |- + BaseURLResolution declaratively describes a post-token-exchange lookup an + OAuth-backed tool needs to compute its real request base_url (e.g. Jira + Cloud's per-site cloudId indirection). strategy is a oneof so exactly one + resolution kind can ever be set at a time; "http_lookup" is the only kind + implemented today, see action-executor/internal/credentials for the + generic resolver that executes this recipe. + additionalProperties: false +http_execution: + type: object + properties: + baseUrl: + type: string + example: https://api.example.com + path: + type: string + example: /search + method: + type: string + example: POST + allowedHosts: + type: array + items: + type: string + example: + - api.example.com + requestEncoding: + type: string + example: json + responseFormat: + type: string + example: json + additionalProperties: false +http_lookup_spec: + type: object + properties: + method: + type: string + example: POST + url: + type: string + example: https://api.example.com/resources + matchField: + type: string + example: id + matchValue: + type: string + example: site-123 + caseInsensitive: + type: boolean + example: false + trimTrailingSlash: + type: boolean + example: true + extractField: + type: string + example: url + baseUrlTemplate: + type: string + example: https://{value} + requiredScopes: + type: array + items: + type: string + example: + - read + match_value_parameter: + type: string + example: site_id + description: |- + HTTPLookupSpec resolves a base_url by calling url (bearer-authenticated + with the just-exchanged access token), selecting an entry in the JSON array, + extracting extract_field from that entry, and substituting it for "{value}" + in base_url_template. When match_field and match_value are both set, they + select the entry. When both are empty, exactly one entry whose own "scopes" + array contains required_scopes must exist. Configuring only one match field + is invalid. Resolution fails fast on zero or multiple compatible entries. + additionalProperties: false +mcp_execution: + type: object + properties: + endpoint: + type: string + example: https://mcp.example.com + toolName: + type: string + example: search + transport: + type: string + example: streamable_http + serverRef: + type: string + example: provider-mcp + allowedHosts: + type: array + items: + type: string + example: + - api.example.com + description: |- + MCPExecution describes how to invoke a tool that is fronted by a remote + MCP server (as opposed to a plain HTTP endpoint). endpoint is the remote + MCP server's URL, tool_name is the name the remote server expects on + tools/call (may differ from this tool's registry name), transport + selects the wire protocol ("streamable_http" is the only kind implemented + today), and server_ref is an opaque label identifying the remote server + for logging/metrics/allowlisting. + additionalProperties: false diff --git a/specification/resources/action_gateway/parameters.yml b/specification/resources/action_gateway/parameters.yml new file mode 100644 index 00000000..8f40fbfc --- /dev/null +++ b/specification/resources/action_gateway/parameters.yml @@ -0,0 +1,33 @@ +toolbelt_name: + name: name + in: path + required: true + description: The natural key identifying the toolbelt. + schema: + type: string + pattern: '^[a-z][a-z0-9_-]{0,63}$' + example: search-toolbelt + +toolbelt_version: + name: version + in: query + required: false + description: An immutable numeric toolbelt version. Omit to retrieve the latest active version. + schema: + type: string + pattern: '^[0-9]+$' + example: '1' + +toolbelt_status: + name: status + in: query + required: false + description: Filter toolbelts by status. + schema: + type: string + enum: + - active + - deprecated + - all + default: active + example: active diff --git a/specification/resources/action_gateway/response_headers.yml b/specification/resources/action_gateway/response_headers.yml new file mode 100644 index 00000000..c8ac026b --- /dev/null +++ b/specification/resources/action_gateway/response_headers.yml @@ -0,0 +1,6 @@ +ratelimit-limit: + $ref: '../../shared/headers.yml#/ratelimit-limit' +ratelimit-remaining: + $ref: '../../shared/headers.yml#/ratelimit-remaining' +ratelimit-reset: + $ref: '../../shared/headers.yml#/ratelimit-reset' diff --git a/specification/resources/action_gateway/sessions_create.yml b/specification/resources/action_gateway/sessions_create.yml new file mode 100644 index 00000000..e69a2efb --- /dev/null +++ b/specification/resources/action_gateway/sessions_create.yml @@ -0,0 +1,42 @@ +operationId: sessions_create +summary: Create an Action Gateway Session +description: Creates a session with a tool selection, invocation policy, and + optional direct-tool preload configuration. +tags: + - Action Gateway +requestBody: + required: true + content: + application/json: + schema: + $ref: models.yml#/create_session_request + examples: + sessions_create_request: + $ref: examples.yml#/sessions_create_request +responses: + "200": + description: The session was created successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/create_session_response + examples: + sessions_create_response: + $ref: examples.yml#/sessions_create_response + "400": + $ref: ../../shared/responses/bad_request.yml + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:create +x-codeSamples: + - $ref: examples/curl/sessions_create.yml diff --git a/specification/resources/action_gateway/sessions_delete.yml b/specification/resources/action_gateway/sessions_delete.yml new file mode 100644 index 00000000..ad413318 --- /dev/null +++ b/specification/resources/action_gateway/sessions_delete.yml @@ -0,0 +1,40 @@ +operationId: sessions_delete +summary: Delete an Action Gateway Session +description: Deletes an Action Gateway session owned by the authenticated team. +tags: + - Action Gateway +parameters: + - name: session_urn + in: path + required: true + description: The URL-encoded managed agents session URN. + schema: + type: string + example: do:managed_agents_session:123e4567-e89b-12d3-a456-426614174000 +responses: + "200": + description: The session was deleted successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/delete_session_response + examples: + sessions_delete_response: + $ref: examples.yml#/sessions_delete_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:delete +x-codeSamples: + - $ref: examples/curl/sessions_delete.yml diff --git a/specification/resources/action_gateway/sessions_list.yml b/specification/resources/action_gateway/sessions_list.yml new file mode 100644 index 00000000..2c8f50e9 --- /dev/null +++ b/specification/resources/action_gateway/sessions_list.yml @@ -0,0 +1,39 @@ +operationId: sessions_list +summary: List Action Gateway Sessions +description: Lists Action Gateway sessions owned by the authenticated team. +tags: + - Action Gateway +parameters: + - name: end_user_id + in: query + description: Filter sessions by actor identifier. + schema: + type: string + example: end-user-123 + - $ref: ../../shared/parameters.yml#/page + - $ref: ../../shared/parameters.yml#/per_page +responses: + "200": + description: Sessions were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_sessions_response + examples: + sessions_list_response: + $ref: examples.yml#/sessions_list_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/sessions_list.yml diff --git a/specification/resources/action_gateway/toolbelts_add_tools.yml b/specification/resources/action_gateway/toolbelts_add_tools.yml new file mode 100644 index 00000000..4f06979f --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_add_tools.yml @@ -0,0 +1,45 @@ +operationId: toolbelts_add_tools +summary: Add Tools to a Toolbelt +description: Adds provider-qualified tool names and creates a new immutable toolbelt version. +tags: + - Action Gateway +parameters: + - $ref: 'parameters.yml#/toolbelt_name' +requestBody: + required: true + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_tools' + examples: + toolbelts_add_tools_request: + $ref: 'examples.yml#/toolbelts_add_tools_request' +responses: + '200': + description: The resulting toolbelt version. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_response' + examples: + toolbelt_response: + $ref: 'examples.yml#/toolbelt_response' + '400': + $ref: '../../shared/responses/bad_request.yml' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '404': + $ref: '../../shared/responses/not_found.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:update +x-codeSamples: + - $ref: examples/curl/toolbelts_add_tools.yml diff --git a/specification/resources/action_gateway/toolbelts_create.yml b/specification/resources/action_gateway/toolbelts_create.yml new file mode 100644 index 00000000..eb7ac43b --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_create.yml @@ -0,0 +1,43 @@ +operationId: toolbelts_create +summary: Create a Toolbelt +description: Creates a versioned collection of provider-qualified Action Gateway tool names. +tags: + - Action Gateway +requestBody: + required: true + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_create' + examples: + toolbelts_create_request: + $ref: 'examples.yml#/toolbelts_create_request' +responses: + '200': + description: A toolbelt was created successfully. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_response' + examples: + toolbelt_response: + $ref: 'examples.yml#/toolbelt_response' + '400': + $ref: '../../shared/responses/bad_request.yml' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '409': + $ref: '../../shared/responses/conflict.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:create +x-codeSamples: + - $ref: examples/curl/toolbelts_create.yml diff --git a/specification/resources/action_gateway/toolbelts_delete.yml b/specification/resources/action_gateway/toolbelts_delete.yml new file mode 100644 index 00000000..f4afe998 --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_delete.yml @@ -0,0 +1,34 @@ +operationId: toolbelts_delete +summary: Delete a Toolbelt +description: Deprecates the latest active version of a toolbelt. +tags: + - Action Gateway +parameters: + - $ref: 'parameters.yml#/toolbelt_name' +responses: + '200': + description: The toolbelt was deprecated successfully. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_response' + examples: + toolbelts_delete_response: + $ref: 'examples.yml#/toolbelts_delete_response' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '404': + $ref: '../../shared/responses/not_found.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:delete +x-codeSamples: + - $ref: examples/curl/toolbelts_delete.yml diff --git a/specification/resources/action_gateway/toolbelts_get.yml b/specification/resources/action_gateway/toolbelts_get.yml new file mode 100644 index 00000000..b1c703d7 --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_get.yml @@ -0,0 +1,35 @@ +operationId: toolbelts_get +summary: Retrieve a Toolbelt +description: Retrieves the latest active version or a specified immutable version of a toolbelt. +tags: + - Action Gateway +parameters: + - $ref: 'parameters.yml#/toolbelt_name' + - $ref: 'parameters.yml#/toolbelt_version' +responses: + '200': + description: The toolbelt was retrieved successfully. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_response' + examples: + toolbelt_response: + $ref: 'examples.yml#/toolbelt_response' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '404': + $ref: '../../shared/responses/not_found.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/toolbelts_get.yml diff --git a/specification/resources/action_gateway/toolbelts_list.yml b/specification/resources/action_gateway/toolbelts_list.yml new file mode 100644 index 00000000..848dbb82 --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_list.yml @@ -0,0 +1,34 @@ +operationId: toolbelts_list +summary: List Toolbelts +description: Lists the latest version of each toolbelt owned by the authenticated team. +tags: + - Action Gateway +parameters: + - $ref: 'parameters.yml#/toolbelt_status' + - $ref: '../../shared/parameters.yml#/page' + - $ref: '../../shared/parameters.yml#/per_page' +responses: + '200': + description: Toolbelts were retrieved successfully. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelts_response' + examples: + toolbelts_list_response: + $ref: 'examples.yml#/toolbelts_list_response' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/toolbelts_list.yml diff --git a/specification/resources/action_gateway/toolbelts_remove_tools.yml b/specification/resources/action_gateway/toolbelts_remove_tools.yml new file mode 100644 index 00000000..d98fbb52 --- /dev/null +++ b/specification/resources/action_gateway/toolbelts_remove_tools.yml @@ -0,0 +1,45 @@ +operationId: toolbelts_delete_tools +summary: Remove Tools from a Toolbelt +description: Removes tool names and creates a new immutable toolbelt version. +tags: + - Action Gateway +parameters: + - $ref: 'parameters.yml#/toolbelt_name' +requestBody: + required: true + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_tools' + examples: + toolbelts_remove_tools_request: + $ref: 'examples.yml#/toolbelts_remove_tools_request' +responses: + '200': + description: The resulting toolbelt version. + headers: + $ref: 'response_headers.yml' + content: + application/json: + schema: + $ref: 'models.yml#/toolbelt_response' + examples: + toolbelt_response: + $ref: 'examples.yml#/toolbelt_response' + '400': + $ref: '../../shared/responses/bad_request.yml' + '401': + $ref: '../../shared/responses/unauthorized.yml' + '404': + $ref: '../../shared/responses/not_found.yml' + '429': + $ref: '../../shared/responses/too_many_requests.yml' + '500': + $ref: '../../shared/responses/server_error.yml' + default: + $ref: '../../shared/responses/unexpected_error.yml' +security: + - bearer_auth: + - genai:delete +x-codeSamples: + - $ref: examples/curl/toolbelts_delete_tools.yml diff --git a/specification/resources/action_gateway/tools_get_definition.yml b/specification/resources/action_gateway/tools_get_definition.yml new file mode 100644 index 00000000..017e1215 --- /dev/null +++ b/specification/resources/action_gateway/tools_get_definition.yml @@ -0,0 +1,52 @@ +operationId: tools_get_definition +summary: Retrieve a Tool Definition +description: Retrieves the executable definition for an active Action Gateway tool. +tags: + - Action Gateway +parameters: + - name: name + in: path + required: true + description: The provider-qualified tool name. + schema: + type: string + example: exa_web_search + - name: version + in: query + description: The tool version. Omit to retrieve the current version. + schema: + type: string + example: v1 + - name: toolkit_id + in: query + description: The toolkit identifier used to disambiguate a bare tool name. + schema: + type: string + example: exa +responses: + "200": + description: The tool definition was retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/tool_definition + examples: + tools_get_definition_response: + $ref: examples.yml#/tools_get_definition_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/tools_get_definition.yml diff --git a/specification/resources/action_gateway/tools_list.yml b/specification/resources/action_gateway/tools_list.yml new file mode 100644 index 00000000..d85f94a1 --- /dev/null +++ b/specification/resources/action_gateway/tools_list.yml @@ -0,0 +1,39 @@ +operationId: tools_list +summary: List Tools +description: Lists active Action Gateway tools visible to the authenticated team. +tags: + - Action Gateway +parameters: + - name: toolkit_id + in: query + description: Filter tools by toolkit identifier. + schema: + type: string + example: exa + - $ref: ../../shared/parameters.yml#/page + - $ref: ../../shared/parameters.yml#/per_page +responses: + "200": + description: Tools were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_tools_response + examples: + tools_list_response: + $ref: examples.yml#/tools_list_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/tools_list.yml diff --git a/specification/resources/action_gateway/tools_list_providers.yml b/specification/resources/action_gateway/tools_list_providers.yml new file mode 100644 index 00000000..b02479aa --- /dev/null +++ b/specification/resources/action_gateway/tools_list_providers.yml @@ -0,0 +1,30 @@ +operationId: tools_list_providers +summary: List Tool Providers +description: Lists Action Gateway providers and their connection requirements. +tags: + - Action Gateway +responses: + "200": + description: Tool providers were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_providers_response + examples: + tools_list_providers_response: + $ref: examples.yml#/tools_list_providers_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/tools_list_providers.yml diff --git a/specification/resources/action_gateway/tools_list_toolkits.yml b/specification/resources/action_gateway/tools_list_toolkits.yml new file mode 100644 index 00000000..df79e36a --- /dev/null +++ b/specification/resources/action_gateway/tools_list_toolkits.yml @@ -0,0 +1,30 @@ +operationId: tools_list_toolkits +summary: List Toolkits +description: Lists the toolkits that group Action Gateway tools. +tags: + - Action Gateway +responses: + "200": + description: Toolkits were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_toolkits_response + examples: + tools_list_toolkits_response: + $ref: examples.yml#/tools_list_toolkits_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/tools_list_toolkits.yml diff --git a/specification/resources/action_gateway/users_get.yml b/specification/resources/action_gateway/users_get.yml new file mode 100644 index 00000000..befcec8f --- /dev/null +++ b/specification/resources/action_gateway/users_get.yml @@ -0,0 +1,41 @@ +operationId: users_get +summary: Retrieve an Action Gateway User +description: Retrieves a derived end-user view containing its sessions and OAuth + connections. +tags: + - Action Gateway +parameters: + - name: user_id + in: path + required: true + description: The end-user identifier. + schema: + type: string + example: end-user-123 +responses: + "200": + description: The user was retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/get_user_response + examples: + users_get_response: + $ref: examples.yml#/users_get_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "404": + $ref: ../../shared/responses/not_found.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/users_get.yml diff --git a/specification/resources/action_gateway/users_list.yml b/specification/resources/action_gateway/users_list.yml new file mode 100644 index 00000000..c559b5f0 --- /dev/null +++ b/specification/resources/action_gateway/users_list.yml @@ -0,0 +1,34 @@ +operationId: users_list +summary: List Action Gateway Users +description: Lists end-user identifiers derived from sessions and OAuth + connections for the authenticated team. +tags: + - Action Gateway +parameters: + - $ref: ../../shared/parameters.yml#/page + - $ref: ../../shared/parameters.yml#/per_page +responses: + "200": + description: Users were retrieved successfully. + headers: + $ref: response_headers.yml + content: + application/json: + schema: + $ref: models.yml#/list_users_response + examples: + users_list_response: + $ref: examples.yml#/users_list_response + "401": + $ref: ../../shared/responses/unauthorized.yml + "429": + $ref: ../../shared/responses/too_many_requests.yml + "500": + $ref: ../../shared/responses/server_error.yml + default: + $ref: ../../shared/responses/unexpected_error.yml +security: + - bearer_auth: + - genai:read +x-codeSamples: + - $ref: examples/curl/users_list.yml