Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Your secret key, rk_test_… or rk_live_…, sent as Authorization: Bearer <key>. Keep it on your server. Restricted keys carry only the scopes you give them.

Headers

Reflections-Version
string

The dated API version. Defaults to the version your account is pinned to.

Example:

"2026-10-15"

Idempotency-Key
string

A unique key for this operation, up to 255 characters. In test mode, POST keys are scoped to your account and mode and bind the endpoint and body for 24 hours. A different endpoint or body with the same key is refused.

Initial live check and generation creation require a nonempty key. Each operation has a separate account-scoped namespace; retain the same API key, body and idempotency key for retries within 24 hours of creation. A pending check returns 202 with status: "checking". Completed checks replay their sealed response; successful generation POSTs replay the original accepted 202, so use GET for current state. Live verification is a read-only query that returns a fresh verification ID on each call, without exact response caching.

The broader delegated-account contract also scopes keys to Reflections-Account; delegated requests and the other planned live POST operations remain unsupported.

Maximum string length: 255

Path Parameters

escalation_id
string
required

The escalation's ID.

Pattern: ^esc_[0-9a-hjkmnp-tv-z]{26}$

Body

application/json
decision
enum<string>
required

For a held output, allow releases it and deny declines it.

Available options:
allow,
deny
decided_by
object
required

The person who made the decision. Recorded on the talent's audit record.

note
string

Shown to the platform as escalation.note.

Maximum string length: 500

Response

The resolved escalation.

An escalation with the request, use and findings a reviewer needs.

id
string
required

The escalation's ID, esc_ followed by 26 characters.

Pattern: ^esc_[0-9a-hjkmnp-tv-z]{26}$
reason
enum<string>
required

judgment: a rule needs a person to read it. unverifiable: a protected attribute could not be confirmed. evaluation_unavailable: the check could not finish. release_review: every output under this license is released by a person.

Available options:
judgment,
unverifiable,
evaluation_unavailable,
release_review
reviewer
enum<string>
required

talent: the talent, or a representative whose mandate has review_outputs. representative: only the talent's representatives. reflections: Reflections trust and safety, under a platform license.

Available options:
talent,
representative,
reflections
status
enum<string>
required

open until it closes: allowed or denied by the reviewer, expired at expires_at, or cancelled when you cancel the check, withdraw the output, or another talent's escalation decides the check.

Available options:
open,
allowed,
denied,
expired,
cancelled
expires_at
string<date-time>
required

When an unanswered escalation becomes deny: 7 days after it opens, or the license's shorter escalation_window.

object
string
required

Always escalation.

Allowed value: "escalation"
livemode
boolean
required

true in live mode, false in test mode.

subject
object
required

What waits on the decision.

talent
string
required

The talent whose side decides. When a check escalates for several talent, each has their own escalation.

Pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$
license
string
required

The license the request was checked under.

Pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$
licensee
string
required

The account that holds license.

Pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$
platform
string
required

The platform that ran the check or submitted the output.

Pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$
use
object
required

The use the platform asked for on the check.

request_digest
string
required

The request_digest of the check. Allowing an escalated check covers exactly this request.

Pattern: ^sha256:[0-9a-f]{64}$
created_at
string<date-time>
required

When the check escalated or the output was held.

resolved_at
string<date-time> | null

When the escalation was decided, expired or cancelled. Null while open.

note
string | null

The reviewer's note, if they wrote one.

Maximum string length: 500
license_revision
string

The revision of license the request was checked against.

Pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$
licensee_name
string

The licensee's account name.

platform_name
string

The platform's account name.

inputs
object[]

The request as the platform sent it. Media inputs carry a url that opens for 15 minutes. Text sent withheld appears as role and sha256 only.

reasons
object[]

What raised the question, with the talent's term.

findings
object[]

For a held output, what Reflections recorded on its bytes.

artifact
object | null

For a held output, the clean bytes to review.

review_url
string<uri> | null

The Talent Portal page where a person with authority reviews it and decides. Present while open.

decision
enum<string> | null

The decision a person recorded, allow or deny. null until one is recorded.

Available options:
allow,
deny,
null
decided_by
object | null

Who resolved it.