DigitalOcean API (unofficial showcase)
POST/tools/invoke

Invoke Session Tools

Runs 1 to 10 tool calls in parallel and returns one result per call, in request order. This is the REST form of the action_invoke MCP tool.

Each call is checked against the session's tool selection and policy, uses the session actor's connections, and applies any output view bound to the tool in the session. A well-formed request returns 200 even when some calls fail. Check each item's result.status, and use success_count and error_count to branch without scanning every item.

A call whose policy requires approval fails with _meta.status set to requires_approval. Have the session's owner approve it, then repeat the call with the same arguments. A call that needs the end user to connect a provider fails with _meta.status set to requires_authorization or requires_connection_configuration.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
X-Session-Idstringrequired
The session to act in: the UUID at the end of the session's `sessionUrn` and `mcpUrl`. The session must belong to the authenticated user and team.
rationalestringoptional
One sentence explaining why the tools are being called. Values longer than 512 characters are truncated.
toolsarray<object>required
The tool calls to run in parallel.

10 status codes
200The calls ran. Each item reports its own success or failure.
total_countintegeroptional
success_countintegeroptional
error_countintegeroptional
resultsarray<object>optional
One result per call, in request order.
400The request is invalid: the body is not valid JSON, a required field is missing, or a value is out of range.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
401The token is missing, invalid, or expired. This response uses the standard DigitalOcean API error format.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
402Your team must add prepayment before it can make more tool calls.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
403The token or session cannot be used for this request. Tokens without the `action_gateway:execute` scope, and accounts that are not in good standing, are rejected with the standard DigitalOcean API error format. Session failures return a tool result: the session ID is missing or invalid, the session belongs to another user or team, the session has no policy, or the session policy denies the operation.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
412Your team is not enabled for Action Gateway, or the session or its connection is not set up for this call. For example, the session needs an `actorId` for OAuth tools, an OAuth connection must be reconnected, or the connection's private network does not match what the MCP server requires.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
413The request body is larger than 1 MiB.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
429A rate limit was exceeded. Wait for the number of seconds in `Retry-After`, when present, before retrying.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
500The gateway failed to process the request. Retry later.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.
503The gateway or a service it depends on is temporarily unavailable. Retry later.
statusstringrequired
Allowed:failed
errorobjectrequired
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this request, when one was assigned.

Error handling

A 400 is returned: The request is invalid: the body is not valid JSON, a required field is missing, or a value is out of range. A 401 is returned: The token is missing, invalid, or expired. This response uses the standard DigitalOcean API error format. A 402 is returned: Your team must add prepayment before it can make more tool calls. A 403 is returned: The token or session cannot be used for this request. Tokens without the action_gateway:execute scope, and accounts that are not in good standing, are rejected with the standard DigitalOcean API error format. Session failures return a tool result: the session ID is missing or invalid, the session belongs to another user or team, the session has no policy, or the session policy denies the operation. A 412 is returned: Your team is not enabled for Action Gateway, or the session or its connection is not set up for this call. For example, the session needs an actorId for OAuth tools, an OAuth connection must be reconnected, or the connection's private network does not match what the MCP server requires. A 413 is returned: The request body is larger than 1 MiB. A 429 is returned: A rate limit was exceeded. Wait for the number of seconds in Retry-After, when present, before retrying. A 500 is returned: The gateway failed to process the request. Retry later. A 503 is returned: The gateway or a service it depends on is temporarily unavailable. Retry later.