/api-reference/openapi.yaml. Its
x-reflections-availability field distinguishes source support in each mode from planned contracts;
it does not establish production activation.
A supported endpoint may still have unsupported input forms; read its availability notice.
Native TypeScript fetch, Python standard-library and Go net/http samples need no Reflections SDK.
For each new logical POST, generate a UUID once and save it with the request body. Set the
operation-specific environment variable named in the sample, such as
REFLECTIONS_CREATE_CHECK_IDEMPOTENCY_KEY. Keep the same value and body on retries; choose a new
value for a new request. Object IDs in endpoint examples are illustrative: replace them with the
IDs your earlier calls returned. The quickstart does both automatically.
Base URL
Content-Type: application/json). File uploads and multipart
verification are planned. Responses are JSON, and errors are
problem details (application/problem+json).
Every /v1 endpoint is under the base URL. A few routes are not under /v1: they are at the
origin root, https://app.reflections.ai. Only discovery and JWKS are currently served from this
table; the session stream, Talent API OAuth and Talent API MCP are planned:
The OAuth and
/mcp paths in the table are also at the origin root.
Test and live mode
Test keys (rk_test_) return objects with livemode: false and use fictional fixtures.
They cannot approve use of a real person’s identity. Create a test or live key in the
dashboard; keep it on your server. A key needs a
Reflections account: sign in with either option on the sign-in page, and you return to the keys page.
The three live reads covered by the recorded production release are:
These live objects carry
livemode: true. License reads require licenses:read on a restricted
key. Delegated connections are planned: the caller must own the license. Responses expose the
current signed revision’s identity and digest, with only the supported scope fields.
They expose no private reference IDs or source media. Omitted fields grant nothing.
Initial live image implementation
Live image checks, output submission and receipts are built but not yet activated: until activation, a livePOST /v1/checks or POST /v1/generations returns 403
live_not_activated. Retrying does not help; use a test
key until Reflections confirms activation. The source supports six operations for this journey.
The check requires one explicit license, text inputs totaling at most 64 KiB, image depiction,
commercial advertising or branded content,
execution.candidates: 1, and on_escalate: "deny".
Every channel and territory must match the signed scope; only signed WW means worldwide.
The provider and model must match the later generation. job_id is optional and can be supplied
after the provider starts the job. Generations accept only an inline still PNG, at most 7 MiB
decoded, with its exact SHA-256. Reflections evaluates the submitted bytes; it does not render an
image or fetch an output from a provider or URL.
The license must newly sign externalCreation: "images.v1" and
externalCreationPostRevocation: "retain". Existing signatures grant neither by omission.
Every image requires the talent’s actual release before decision: "allow"; a successful upload
or evaluator result is insufficient. Live signing additionally requires protected operator
activation after the public key’s 30-day publication period. That activation is not established.
Private check and generation detail remains available while pending and for 24 hours after its
terminal retention boundary, then returns 404. Signed receipts have a separate seven-year
retention period. See Privacy and
production qualification.
Live check/generation lists, cancellation and withdrawal, revisions, talent/facets, delegated
connections, revocation feeds, files, video, OAuth and webhooks remain unsupported. Receipt retrieval is keyless in both modes. Verification looks only in the caller’s mode: a test
receipt needs a test key, and verifying it with a live key or no key returns result: "not_found". Reading a live license
alone does not authorize generation.
Two sides
Most endpoints serve the side that uses a license: licensees and the platforms that act for them check uses, submit outputs, report usage and honor revocations. The talent side serves representatives, such as agencies and managers, acting for a talent under a mandate: the escalation queue, license drafts, declining requests, suspending and revoking licenses, and confirming or disputing statements. A license is only ever signed by a person, on a hosted page. See Talent representatives.Headers
Objects
Every object has anid and an object field naming its type. IDs are a prefix, an underscore and
26 characters of lowercase Crockford base32, which has no i, l, o or u, such as
chk_3m7p4r6s9t0wxyhk5zba2q8v1n. Treat them as opaque strings.
An escalation also appears inside its check or generation, as
escalation. Some IDs appear only
inside other objects and have no endpoint of their own:
The test helpers act as a talent or a
reviewer in test mode. They create no objects of their own.
Lists
Every list endpoint returns the same envelope, newest first:next_cursor as cursor to read the next page. See Pagination.
IDs, not nested objects
A field that names another object holds its ID. A check’sreceipt is rcpt_…, a generation’s
check is chk_…, and a license’s talent is tal_…. There is no expand parameter: retrieve
the other object from its own endpoint.
A response embeds a nested object only where you need it in the same call:
Formats
A statement’s
amount_due, amount_paid and line amount values are integers in the statement’s
currency. Never put personal data in metadata.
Where to go next
Authentication
Keys, scopes, and acting for a licensee.
Errors
The problem format and every error code.
Webhooks
Signatures, retries, ordering and replay.
Authorization token
The token a tool verifies before it generates.