DigitalOcean API (unofficial showcase)
POST/tools/search

Search Session Tools

Finds the catalog tools that fit one or more use cases. This is the REST form of the action_search MCP tool. Each query is searched independently and returns its own result group, so you can see which tools serve which goal. Results include each tool's inputSchema, so you can call a tool with POST /tools/invoke without another lookup.

Results include only tools that the session can call. If the session policy requires approval for action_search, the response is a failed result with _meta.status set to requires_approval.

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

1 parameter · 4 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.
queriesarray<object>required
Independent search queries. Split separate actions into separate queries. Each query is searched on its own and gets its own result group.
providersarray<string>optional
Restricts every query to these providers.
tagsarray<string>optional
Restricts every query to tools with these tags.
limitintegeroptional
The maximum number of tools returned per query. Values above 50 are capped at 50.
Default:10

9 status codes
200The search ran, or it is waiting for approval. Check `status` before reading `output`.
statusstringrequired
Allowed:succeededfailed
outputobjectoptional
errorobjectoptional
Describes why a request or tool call failed and whether retrying can help.
call_idstringrequired
A unique identifier for this call. Include it when contacting support.
_metaobjectoptional
Additional result metadata. Keys include: - `status`: `requires_approval`, `requires_authorization`, or `requires_connection_configuration` when the call stopped before running. - `approval_id`, `tool_name`, `expires_at`, and `decide`: present with `requires_approval`. `decide` gives the `method`, `path`, and `body` of the approval request to send. Approve the call, then repeat it with the same arguments before `expires_at`. - `retry`: `{"attempt_count": N, "exhausted": bool}` when the gateway retried the call. - `output_view`: the output view applied to the result.
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.
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 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.