Approvals - Hexel Studio

Some actions shouldn’t run unattended. Approvals let you — or your policies — gate execution before it happens. An agent that drafts a customer email might proceed autonomously, but one that issues refunds should wait for a human thumbs-up. This is where you draw that line. Approvals pause a task in plan_review until someone approves or rejects the plan. Policies evaluate automatically whether work should be allowed, denied, or require approval.

Approval statuses

Status	Meaning
`PENDING`	Awaiting a reviewer’s decision.
`APPROVED`	Approved; execution proceeds.
`REJECTED`	Rejected; task moves to `cancelled`.
`CANCELLED`	Withdrawn before a decision was made.
`EXPIRED`	Not decided within 24 hours (hardcoded; not configurable).

Pending approvals expire after exactly 24 hours. There is no way to extend this window.

Policy outcomes

Policies evaluate a plan and return one of:

Outcome	Effect
`ALLOW`	Execution proceeds without review.
`DENY`	Execution is blocked immediately.
`REQUIRE_APPROVAL`	An approval request is created; task waits.

How it works

SDK operations

Approvals (`/v1/approvals`)

Operation	SDK
List approvals	`client.orchestrator.approval.list()`
Get approval	`client.orchestrator.approval.get(approval_id)`
Review (approve/reject)	`client.orchestrator.approval.review(approval_id, decision=...)`

Policies (`/v1/policies`)

Operation	SDK
List policies	`client.orchestrator.policy.list()`
Get policy	`client.orchestrator.policy.get(policy_id)`
Evaluate	`client.orchestrator.policy.evaluate(context=...)`

Review an approval

Python

# List pending approvals
approvals = client.orchestrator.approval.list()

# Inspect one
approval = client.orchestrator.approval.get("YOUR_APPROVAL_ID")
print(approval["status"])  # PENDING

# Approve
client.orchestrator.approval.review("YOUR_APPROVAL_ID", decision="approve")

# Reject
client.orchestrator.approval.review("YOUR_APPROVAL_ID", decision="reject")

Evaluate a policy

Test what outcome a given context would produce without creating a real task:

result = client.orchestrator.policy.evaluate(
    context={"action": "send_email", "scope": "external"}
)
print(result["outcome"])  # ALLOW | DENY | REQUIRE_APPROVAL

Errors

HTTP	Message	When
`400`	`invalid request` (with details)	Malformed review payload.
`400`	`invalid id`	The approval ID isn’t a valid identifier.
`404`	not found	The approval doesn’t exist or isn’t in your scope.

Security

Requirement	Detail
Review permission	Reviewing an approval requires the appropriate RBAC permission for your organization.
Scoping	Approvals are scoped to your organization, workspace, and environment.
Expiry	Pending approvals expire automatically after 24 hours if no decision is made. Build approval review into your operational workflow so tasks don’t stall indefinitely.

Rate limits

100 requests per organization per minute. Pagination: page >= 1, page_size 1–100 (default 20).

Common errors

Code	Meaning
`404`	Approval or policy not found.
`409`	Approval already reviewed or expired.
`422`	Invalid decision value.
`429`	Rate limit exceeded.

Expiry behavior

When an approval expires (24h without a decision), the task moves to cancelled. There is no retry; submit a new task if the work should still be done.

Tasks

The work approvals gate.

Streaming & Replay

See approval events in the stream.

Members & Roles

Who can approve.

Tasks & Workflows

Where plan review fits in the lifecycle.

Next steps

Continue to Streaming & Replay.

​Approval statuses

​Policy outcomes

​How it works

​SDK operations

​Approvals (/v1/approvals)

​Policies (/v1/policies)

​Review an approval

​Evaluate a policy

​Errors

​Security

​Rate limits

​Related pages

Tasks

Streaming & Replay

Members & Roles

Tasks & Workflows

​Next steps

Approval statuses

Policy outcomes

How it works

SDK operations

Approvals (`/v1/approvals`)

Policies (`/v1/policies`)

Review an approval

Evaluate a policy

Errors

Security

Rate limits

Related pages

Next steps