DigitalOcean API (unofficial showcase)
POST/code/execute

Execute Code

Runs Python code in an ephemeral sandbox and returns its stdout, stderr, and exit_code. This is the REST form of the action_code MCP tool. Use it for computation, parsing, and data processing, or to chain several catalog tools in one request.

The sandbox provides invoke_digitalocean_tool(name, arguments), which calls a catalog tool and returns a tool result. Those calls follow the session's tool selection and policy. Each request runs in a fresh sandbox, so state is not kept between requests. Execution, including tool calls, is time limited. Code that runs too long fails with a timeout error.

A nonzero exit code is still a succeeded result; check output.exit_code. If the session policy requires approval for action_code, 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 · 1 body field
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.
codestringrequired
Python source to run. The sandbox provides `invoke_digitalocean_tool(name: str, arguments: dict) -> dict`, which calls a catalog tool under the session's policy and returns a tool result.

10 status codes
200The code 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.
504The code did not finish within the execution time limit.
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. A 504 is returned: The code did not finish within the execution time limit.