Skip to main content
Sandbox and protocol reference. Sandbox escalations are controlled by test fixtures and the test helper, not sent to a real talent or reviewer. Production review queues and webhook delivery remain planned. Start with the runnable quickstart and sandbox support matrix.
An escalate decision means a person with authority must decide before a use starts or an output is delivered. The response returns at once with an escalation object; nobody waits on an open connection. Until the escalation resolves, you do not generate and you do not deliver.

​
The escalation object

When a request invokes several talent and more than one escalates, each has their own escalation, named in talent[].escalation. The check is allowed only when every one allows, and denied at the first deny or expiry. See Multi-talent requests.

​
Why a request escalates

Two things never escalate. A use no license covers is deny with a license_request remedy, because a license request is a negotiation and a generation cannot wait on one. A use the talent prohibits is deny with talent_prohibits.

​
Who reviews

​
At the check

Show your user a pending state and listen for check.resolved. You may also poll GET /v1/checks/{check_id}, at most once every 5 seconds.
  • On allow, the check’s authorization covers exactly the request you escalated, bound by its request_digest. Changing the prompt or a reference needs a new check.
  • On deny, the check’s status is denied. The reason is review_declined when the reviewer declined, or hold_expired when nobody answered in time. reasons[].sentence says why in the license’s words.
  • If your user leaves, cancel the check with POST /v1/checks/{check_id}/cancel. The reviewer is told, and the check becomes cancelled.

​
At the generation

Under a license with release_policy: "per_output_review", every output that passes its checks returns escalate with status: "held" and the hold_until_release obligation. Keep the clean output private. If the generation carries draft_watermark, you may show a watermarked preview; otherwise show nothing. Deliver only after generation.released. If the reviewer declines, the generation ends denied with review_declined, sent as generation.denied. Files a held output needs are kept past the usual 24 hours. Privacy says how long.

​
How long it can take

An escalation expires 7 days (P7D) after it opens, unless the license’s escalation_window is shorter. expires_at is the exact time.
  • An expired check escalation ends the check with status denied, decision deny and the reason hold_expired, delivered as check.resolved. The escalation’s own status is expired.
  • An expired held output ends with status expired, decision deny and the reason review_expired, delivered as generation.expired. It can never be released.
A check’s status expired means something else: an allowed check whose authorization expired before it was used. An escalated check never ends expired. A revocation while an escalation is open ends it: the check ends denied with license_revoked, and a held output ends denied with license_revoked, sent as generation.denied, and can no longer be released.

​
Interactive products

A chat, a voice call or any product where a user is waiting should not sit on a review queue. Pass on_escalate: "deny" on the check. Anything that would escalate returns deny at once with review_required and a retry_with_hold remedy, so you can offer the user a reviewed path later. Sessions always behave this way, and a license that holds every output for release cannot start a session (session_not_permitted).

​
Example: a rule that needs a person

Ridgeline asks for Maya Okafor at a trailhead café. Her rule “Do not show alcohol or tobacco.” needs a person to judge the request:
When Maya Okafor’s manager allows it, your endpoint receives:
The authorization covers the request exactly as it was escalated, until its expires_at.

Handling escalations

Pending states, webhooks, polling and on_escalate.

Decisions

The three decisions and the check statuses.

Talent representatives

Reviewing escalations for a talent.