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"

Reflections-Account
string

Act for a connected licensee. The value is the licensee's account ID. Requires an active connection between that account and yours.

Pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$
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

session_id
string
required

The session's ID.

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

Response

The ended session.

id
string
required

The session's ID, ses_ followed by 26 characters.

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

Always session.

Allowed value: "session"
livemode
boolean
required

true in live mode, false in test mode.

status
enum<string>
required

active: renew and submit samples. denied: the check did not allow it; reasons say why. ended: you ended it. terminated: Reflections ended it; termination says why.

Available options:
active,
denied,
ended,
terminated
check
string
required

The check Reflections ran on the session's inputs when it started.

Pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$
created_at
string<date-time>
required

When the session started.

license
string | null

The license the session runs under. Null when none applies.

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

The talent the session covers.

Pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$
token
string | null

A JWS with typ tlp-session+jwt. Null when the session is not active.

expires_at
string<date-time> | null

When the current token expires, 5 minutes after it was issued. Null when the session is not active.

renew_every
string

How often to renew the token: PT60S.

Example:

"P30D"

sampling
object

Which samples to submit, and how often.

obligations
object[]

What you must do for the whole session, such as show the disclosure.

reasons
object[]

Why the session was denied. Empty otherwise.

stream_url
string<uri> | null

The session stream's WebSocket URL. Stay connected to receive session.terminated. Null when the session is denied.

termination
object | null

Why and when Reflections ended the session. Null unless status is terminated. The session stream's session.terminated message carries the same fields.

ended_at
string<date-time> | null

When you ended the session with POST /v1/sessions/{session_id}/end. Null until then.

metadata
object

Your metadata from the request.