Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

UpdateApprovalAction

Updates an approval request with the terminal decision (APPROVED or REJECTED). A single operation handles both verbs via the action enum.

Request Syntax


POST /agents/agent-space/agentSpaceId/approvals/approvalId/update-action HTTP/1.1
Content-type: application/json

{
   "action": "string",
   "finalPattern": { 
      "argumentPins": { 
         "string" : "string" 
      },
      "tool": "string"
   },
   "reason": "string",
   "singleUse": boolean,
   "ttlSeconds": number
}

URI Request Parameters

The request uses the following URI parameters.

agentSpaceId

The agent space identifier — multi-tenant workspace scope. Bound from the request URI.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

approvalId

Identifier of the approval request being resolved. A UUID. Bound from the request URI.

Pattern: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}

Required: Yes

Request Body

The request accepts the following data in JSON format.

action

The action to take on the approval request — APPROVED or REJECTED.

Type: String

Valid Values: APPROVED | REJECTED

Required: Yes

finalPattern

The finalized pattern (tool + argumentPins) that scopes the approval. Required when `action` is APPROVED; must be absent when `action` is REJECTED. The pattern narrows, and must not widen, the invocation originally requested by the agent. This cross-field invariant is enforced by service-side validation.

Type: ApprovalPattern object

Required: No

reason

Optional free-text rationale for the decision. Permitted when `action` is REJECTED; ignored when `action` is APPROVED.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

singleUse

Whether the approved action backs a single executed tool call (true) or is reusable within ttlSeconds (false). Required when `action` is APPROVED; must be absent when `action` is REJECTED. When true, ttlSeconds must be absent (the redemption window collapses to the single use). When false, ttlSeconds is required and bounds the reuse window. Cross-field invariants are enforced by service-side validation.

Type: Boolean

Required: No

ttlSeconds

Approval lifetime in seconds, starting from when the decision is submitted. Required when `action` is APPROVED AND `singleUse` is false; must be absent when `action` is REJECTED or when `singleUse` is true (a single-use approval backs one executed action and the redemption window collapses). Cross-field invariants are enforced by service-side validation; the @range bound here is the operation-boundary check that always applies (a maximum of 4 hours).

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 14400.

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "approvalId": "string",
   "expiresAt": number,
   "status": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

approvalId

Identifier of the approval request that was resolved. Echoed back so the client can correlate the response with the request.

Type: String

Pattern: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}

expiresAt

Absolute timestamp at which the approval expires. Set when status is APPROVED (computed as the submission time plus ttlSeconds); absent when status is REJECTED.

Type: Timestamp

status

Lifecycle status of the approval request immediately after submission. Expected post-submission states are APPROVED (when the action is APPROVED) or REJECTED (when the action is REJECTED); PENDING is not returned from this operation, and REVOKED and REDEEMED are reachable only via subsequent reads.

Type: String

Valid Values: PENDING | APPROVED | REJECTED | REVOKED | REDEEMED

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

Access to the requested resource is denied due to insufficient permissions.

message: Detailed error message describing why access was denied.

HTTP Status Code: 403

ConflictException

The request conflicts with the current state of the resource.

message: Detailed error message describing the conflict.

HTTP Status Code: 409

ContentSizeExceededException

This exception is thrown when the content size exceeds the allowed limit.

HTTP Status Code: 413

InternalServerException

This exception is thrown when an unexpected error occurs in the processing of a request.

HTTP Status Code: 500

InvalidParameterException

One or more parameters provided in the request are invalid.

message: Detailed error message describing which parameter is invalid and why.

HTTP Status Code: 400

ResourceNotFoundException

The requested resource could not be found.

message: Detailed error message describing which resource was not found.

HTTP Status Code: 404

ServiceQuotaExceededException

The request would exceed the service quota limit.

message: Detailed error message describing which quota was exceeded.

HTTP Status Code: 402

ThrottlingException

The request was throttled due to too many requests. Please slow down and try again.

message: Detailed error message describing the throttling condition.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by the service.

fieldList: A list of specific failures encountered while validating the input. A member can appear in this list more than once if it failed to satisfy multiple constraints.
message: A summary of the validation failure.

HTTP Status Code: 400