DigitalOcean API (unofficial showcase)
POST/approvals/session/{session_id}/{approval_id}

Decide a Pending Approval

Approves or denies a tool call that is waiting for approval. A tool result returns _meta.status set to requires_approval when the session policy sets ask for the call, and its _meta.decide gives this request's path.

Send the decision with the session owner's token. Approval is a separate control request, not a tool, so an agent cannot approve its own calls. After approving, repeat the original call with the same arguments before expires_at. An approval applies only to that session, tool version, and set of arguments, and is used once. To ask again after a denial or expiry, repeat the tool call.

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

2 parameters · 1 body field
session_idstringrequired
The session UUID: the value at the end of the session's `sessionUrn` and `mcpUrl`. The session must belong to the authenticated user and team.
approval_idstringrequired
The `approval_id` from a tool result whose `_meta.status` is `requires_approval`.
decisionstringrequired
Whether to let the pending call run.
Allowed:approvedeny

10 status codes
200The decision was recorded.
idstringoptional
The approval ID.
statusstringoptional
Allowed:approveddenied
expires_atstringoptional
Repeat an approved call with the same arguments before this time.
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.
404The approval does not exist or belongs to another session. Approvals for other callers are reported as not found.
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.
409The approval was already decided or has expired. Repeat the tool call to request a new approval.
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.
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 404 is returned: The approval does not exist or belongs to another session. Approvals for other callers are reported as not found. A 409 is returned: The approval was already decided or has expired. Repeat the tool call to request a new approval. 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 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.