> ## Documentation Index > Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > The OpenAPI document at /api-reference/openapi.yaml defines the target contract. Its x-reflections-availability field and each operation's availability notice identify supported test and live forms. Do not infer implementation from a schema or code sample. Live keys support account details, reads of the licenses the calling account holds as licensee or issued as talent (GET /v1/licenses?role=issuer), and GET /v1/generations?license=… for the state of outputs under such a license (summaries only: no prompt, reference, bytes or metadata). Live image checks, submissions and receipts are built but not activated: until activation, a live POST /v1/checks or /v1/generations returns 403 live_not_activated, which must not be retried. Discovery and JWKS are at the origin root (https://app.reflections.ai/.well-known/...), not under /v1. > Three rules hold everywhere: a decision is never an error (deny and escalate are 200 responses, and a live check still evaluating is a 202 with status checking); generate nothing for a named talent without an allow; deliver nothing until the generation is allow. > The sandbox accepts personal rk_test_ keys. Persist a separate Idempotency-Key and body for each logical /v1 POST; retry an unknown outcome with the same key and body. OAuth and Talent API MCP remain planned. # Request a license > **Planned contract — unavailable in test and live modes.** This operation is a protocol reference, not a callable endpoint. Start with the [working sandbox quickstart](/quickstart). Asks a talent for a new license, or for a wider one (`kind: change`). The talent or their representative answers in the Talent Portal or through the API: they may change any term, and only a person's signature makes a license. A request grants nothing. When it is signed, the licensee receives `license.issued` and accepts the license in the hosted acceptance page. No endpoint signs or accepts a license. Restricted keys need `license_requests:write`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /license_requests openapi: 3.1.0 info: title: Reflections Talent API version: '2026-10-15' summary: The license server for a person's name, likeness and voice in generative AI. description: > This document defines the target Talent API contract. Each operation declares its current test and live availability. Test mode serves a limited fictional sandbox. Live keys support account details and reading the caller's own licenses. The initial live image check, submission and receipt implementation is deployed, but requires separate live signing activation and production acceptance. Start at https://docs.reflections.ai/quickstart for test mode. The target API lets any product that can generate a real person check whether a use is licensed, verify the output it made, prove that verification to anyone downstream, report usage, and honor revocations. Protected requests use a secret key in the `Authorization` header. The target contract defines test keys (`rk_test_…`) and live keys (`rk_live_…`) use the same base URL; the key decides the mode. A decision is never an error. `deny` and `escalate` are `200` responses that carry a decision. Errors use RFC 9457 problem details. contact: name: Reflections developer support url: https://docs.reflections.ai/production/support email: developers@reflections.ai servers: - url: https://app.reflections.ai/v1 description: >- Fictional test sandbox and conditional live support; availability and activation are separate security: - SecretKey: [] tags: - name: Account description: The account that owns the calling key. - name: Talent description: >- People whose name, likeness and voice are protected and licensed through Reflections. - name: Facets description: >- The parts of a talent's identity a license can cover, such as a voice or a likeness. - name: Resolutions description: Find which talent a prompt, image or voice sample invokes. - name: Licenses description: Signed licenses and their revisions. - name: License requests description: Ask a talent for a new license or a wider one. - name: Connections description: A licensee's permission for a platform to use its licenses. - name: Files description: References and outputs uploaded for checks and generations. - name: Checks description: Decide whether a use may proceed, before anything is generated. - name: Generations description: Check an output against the license its check relied on. - name: Sessions description: Authorize live voice and video with short-lived tokens and sampled checks. - name: Receipts description: Signed, portable proof of a decision. - name: Verifications description: Verify a file, manifest or receipt. - name: Revocations description: Every narrowing of consent, and the platform's acknowledgement of it. - name: Usage records description: Report usage for settlement and audit. - name: Statements description: Monthly amounts owed under a license, reconciled against observed usage. - name: Mandates description: A representative's authority to act for a talent, and its powers. - name: Escalations description: >- The review queue. Checks and held outputs waiting for the talent's side to decide. - name: License drafts description: Terms prepared for a talent's signature. Only a person signs. - name: Webhook endpoints description: Where Reflections sends events. - name: Events description: The record of everything that happened to your objects. - name: Test helpers description: Act as a talent or reviewer in test mode. - name: Discovery description: The public discovery document and signing keys. Neither needs a key. - name: OAuth description: > Authorization for connections, MCP clients and RSL clients, and the metadata that describes it. paths: /license_requests: post: tags: - License requests summary: Request a license description: > **Planned contract — unavailable in test and live modes.** This operation is a protocol reference, not a callable endpoint. Start with the [working sandbox quickstart](/quickstart). Asks a talent for a new license, or for a wider one (`kind: change`). The talent or their representative answers in the Talent Portal or through the API: they may change any term, and only a person's signature makes a license. A request grants nothing. When it is signed, the licensee receives `license.issued` and accepts the license in the hosted acceptance page. No endpoint signs or accepts a license. Restricted keys need `license_requests:write`. operationId: createLicenseRequest parameters: - $ref: '#/components/parameters/ReflectionsVersion' - $ref: '#/components/parameters/ReflectionsAccount' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LicenseRequestCreate' examples: add_channel: summary: Ask to add TV after a denied check value: kind: change talent: tal_9t0wxyhk5zba2q8v1m3n7p4r6s license: lic_k5zba2q8v1m3n7p4r6s9t0wxyh check: chk_8v1m3n7p4r6s9t0wxyhk5zba2q requested_scope: channels: - social - web - tv final_deliverables: 30 offer: type: flat flat: amount: 1000000 currency: usd schedule: on_acceptance note: >- We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs. metadata: campaign: trail-winter-tv responses: '200': description: The license request. headers: Request-Id: $ref: '#/components/headers/RequestId' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/LicenseRequest' examples: sent: summary: A change request waiting for the talent value: id: lrq_py3xqfvbjjcdhvf33y6c2w26jm object: license_request livemode: true kind: change status: sent talent: tal_9t0wxyhk5zba2q8v1m3n7p4r6s licensee: acct_2q8v1m3n7p4r6s9t0wxyhk5zba license: lic_k5zba2q8v1m3n7p4r6s9t0wxyh license_revision: null check: chk_8v1m3n7p4r6s9t0wxyhk5zba2q requested_scope: channels: - social - web - tv final_deliverables: 30 offer: type: flat flat: amount: 1000000 currency: usd schedule: on_acceptance note: >- We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs. decision_note: null signed_at: null declined_at: null withdrawn_at: null metadata: campaign: trail-winter-tv created_at: '2026-10-17T18:10:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' security: - SecretKey: - license_requests:write x-codeSamples: - lang: bash label: cURL source: > # Set a unique key once per new action; persist it and reuse it for every retry. : "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}" : "${REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY:?Set REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY before running this example}" curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/license_requests' \ -H "Authorization: Bearer $REFLECTIONS_KEY" \ -H "Reflections-Version: 2026-10-15" \ -H "Idempotency-Key: $REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ --data-raw '{ "kind": "change", "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s", "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh", "check": "chk_8v1m3n7p4r6s9t0wxyhk5zba2q", "requested_scope": { "channels": [ "social", "web", "tv" ], "final_deliverables": 30 }, "offer": { "type": "flat", "flat": { "amount": 1000000, "currency": "usd" }, "schedule": "on_acceptance" }, "note": "We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs.", "metadata": { "campaign": "trail-winter-tv" } }' - lang: typescript label: TypeScript source: > import { env, exit } from "node:process"; // Set a unique key once per new action; persist it and reuse it for every retry. const apiKey = env.REFLECTIONS_KEY; if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example"); const idempotencyKey = env.REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY; if (!idempotencyKey) throw new Error("Set REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY before running this example"); const response = await fetch("https://app.reflections.ai/v1/license_requests", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Reflections-Version": "2026-10-15", "Idempotency-Key": idempotencyKey, "Content-Type": "application/json", }, body: JSON.stringify({ "kind": "change", "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s", "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh", "check": "chk_8v1m3n7p4r6s9t0wxyhk5zba2q", "requested_scope": { "channels": [ "social", "web", "tv" ], "final_deliverables": 30 }, "offer": { "type": "flat", "flat": { "amount": 1000000, "currency": "usd" }, "schedule": "on_acceptance" }, "note": "We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs.", "metadata": { "campaign": "trail-winter-tv" } }), signal: AbortSignal.timeout(30_000), }); const responseBody = await response.text(); if (!response.ok) { console.error(`HTTP ${response.status}: ${responseBody}`); exit(1); } console.log(responseBody); - lang: python label: Python source: > import json import os from urllib.error import HTTPError from urllib.request import Request, urlopen # Set a unique key once per new action; persist it and reuse it for every retry. apiKey = os.environ["REFLECTIONS_KEY"] if not apiKey: raise ValueError("Set REFLECTIONS_KEY before running this example") idempotencyKey = os.environ["REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY"] if not idempotencyKey: raise ValueError("Set REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY before running this example") headers = { "Authorization": f"Bearer {apiKey}", "Reflections-Version": "2026-10-15", "Idempotency-Key": idempotencyKey, "Content-Type": "application/json", } data = json.dumps({ "kind": "change", "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s", "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh", "check": "chk_8v1m3n7p4r6s9t0wxyhk5zba2q", "requested_scope": {"channels": ["social", "web", "tv"], "final_deliverables": 30}, "offer": { "type": "flat", "flat": {"amount": 1000000, "currency": "usd"}, "schedule": "on_acceptance", }, "note": "We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs.", "metadata": {"campaign": "trail-winter-tv"}, }).encode("utf-8") request = Request("https://app.reflections.ai/v1/license_requests", method="POST", headers=headers, data=data) try: with urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) except HTTPError as error: error_body = error.read().decode("utf-8") raise RuntimeError(f"HTTP {error.code}: {error_body}") from error - lang: go label: Go source: | package main import ( "fmt" "io" "net/http" "os" "strings" "time" ) func main() { // Set a unique key once per new action; persist it and reuse it for every retry. apiKey := os.Getenv("REFLECTIONS_KEY") if apiKey == "" { panic("Set REFLECTIONS_KEY before running this example") } idempotencyKey := os.Getenv("REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY") if idempotencyKey == "" { panic("Set REFLECTIONS_CREATE_LICENSE_REQUEST_IDEMPOTENCY_KEY before running this example") } body := strings.NewReader(`{ "kind": "change", "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s", "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh", "check": "chk_8v1m3n7p4r6s9t0wxyhk5zba2q", "requested_scope": { "channels": [ "social", "web", "tv" ], "final_deliverables": 30 }, "offer": { "type": "flat", "flat": { "amount": 1000000, "currency": "usd" }, "schedule": "on_acceptance" }, "note": "We would like to run the trail campaign images in a TV spot in the US and Canada, with six more final outputs.", "metadata": { "campaign": "trail-winter-tv" } }`) request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/license_requests", body) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Reflections-Version", "2026-10-15") request.Header.Set("Idempotency-Key", idempotencyKey) request.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(request) if err != nil { panic(err) } defer response.Body.Close() responseBody, err := io.ReadAll(response.Body) if err != nil { panic(err) } if response.StatusCode < 200 || response.StatusCode >= 300 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody)) } fmt.Print(string(responseBody)) } components: parameters: ReflectionsVersion: name: Reflections-Version in: header required: false description: >- The dated API version. Defaults to the version your account is pinned to. schema: type: string example: '2026-10-15' ReflectionsAccount: name: Reflections-Account in: header required: false description: > Act for a connected licensee. The value is the licensee's account ID. Requires an active connection between that account and yours. schema: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ IdempotencyKey: name: Idempotency-Key in: header required: false description: > 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. schema: type: string maxLength: 255 schemas: LicenseRequestCreate: type: object required: - kind - talent - requested_scope properties: kind: type: string enum: - new - change description: > `new` for a new license, or `change` for a new revision of the license in `license`, such as a wider scope. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: > The talent to ask. A talent whose `posture.accepts_requests` is `false` takes no requests through the API. license: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: Required for `change`. check: type: string pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$ description: >- The denied check this request answers. The talent sees the use that prompted it. requested_scope: $ref: '#/components/schemas/LicenseScopeRequest' description: > The terms you ask for. A denied check's `remedy.suggested_scope` is a starting point. For `change`, omitted fields keep the current license's terms. offer: $ref: '#/components/schemas/Compensation' description: >- What you offer to pay. The talent's side may sign different compensation. note: type: string maxLength: 2000 description: Shown to the talent as written. metadata: $ref: '#/components/schemas/Metadata' description: Your own key-value pairs, returned on the request. LicenseRequest: type: object required: - id - object - livemode - kind - status - talent - licensee - requested_scope - created_at properties: id: type: string pattern: ^lrq_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier for the request, `lrq_…`. object: type: string const: license_request description: Always `license_request`. livemode: type: boolean description: '`true` for a live-mode request, `false` for a test-mode one.' kind: type: string enum: - new - change description: >- `new` for a new license, or `change` for a new revision of `license`. status: $ref: '#/components/schemas/LicenseRequestStatus' description: >- Where the request stands. Only a `sent` request can be withdrawn or declined. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the request asks. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account that would hold the license: the sender, or the connected licensee a platform sent it for. license: type: - string - 'null' pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: >- For `change`, the license to change. When signed, the license it became. license_revision: type: - string - 'null' pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: >- The revision the talent's side signed. It may differ from what you asked. check: type: - string - 'null' pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$ description: >- The denied check that prompted the request. `null` if none was named. requested_scope: $ref: '#/components/schemas/LicenseScopeRequest' description: The terms asked for, as sent. offer: description: The compensation offered. `null` if the request made no offer. oneOf: - $ref: '#/components/schemas/Compensation' - type: 'null' note: type: - string - 'null' description: The note to the talent, as written. `null` if none was sent. decision_note: type: - string - 'null' description: The talent's note when they declined or signed. signed_at: type: - string - 'null' format: date-time description: > When the talent's side signed a license or revision from the request. `null` unless `signed`. declined_at: type: - string - 'null' format: date-time description: >- When the talent's side declined the request. `null` unless `declined`. withdrawn_at: type: - string - 'null' format: date-time description: When the licensee withdrew the request. `null` unless `withdrawn`. metadata: $ref: '#/components/schemas/Metadata' description: The key-value pairs sent with the request. created_at: type: string format: date-time description: When the request was sent. LicenseScopeRequest: type: object description: >- The scope you ask for. Omitted fields ask for nothing beyond the current license, or for the talent's defaults. properties: facets: type: array items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: The facets you ask for, by ID. facet_types: type: array items: $ref: '#/components/schemas/FacetType' description: > The facet types you ask for, such as `likeness`, when you do not name `facets`. modalities: type: array items: $ref: '#/components/schemas/Modality' description: What you want to generate. kinds: type: array items: $ref: '#/components/schemas/UseKind' description: How the talent would appear. purposes: type: array items: $ref: '#/components/schemas/Purpose' description: What the outputs are for. commercial: type: boolean description: '`true` to ask for commercial use.' channels: type: array items: $ref: '#/components/schemas/Channel' description: > Where outputs would appear. For `change`, list every channel you want, not only the new ones. territories: type: array items: $ref: '#/components/schemas/Territory' description: Where outputs would appear, as ISO 3166-1 alpha-2 codes or `WW`. starts_at: type: string format: date-time description: When you want the license to come into force. ends_at: type: string format: date-time description: When you want the license to end. adjustments: type: array description: Adjustments you ask to be allowed. items: $ref: '#/components/schemas/AdjustmentKind' final_deliverables: type: integer minimum: 1 description: How many outputs you want to deliver in total. sessions: type: boolean description: Ask for live sessions. material_access: type: boolean description: > `true` to ask to download the facets' reference material and send it to a model. platforms: type: array items: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: Platform accounts you want to run checks under the license. sublicense: type: string enum: - none - end_users_personal description: > `end_users_personal` to ask that a platform's end users may make personal, non-commercial outputs. Compensation: type: object description: >- What the licensee owes the talent. Reflections computes statements from it and never moves money. required: - type properties: type: type: string enum: - none - flat - per_unit - revenue_share description: > How the amount owed is set: `none` owes nothing, `flat` is a fixed fee, `per_unit` is a rate per unit of usage, and `revenue_share` is `revenue_share_bps` of revenue. flat: $ref: '#/components/schemas/Money' description: 'The fixed fee, for `type: flat`.' per_unit: type: object description: 'The rate, for `type: per_unit`.' properties: units: type: string enum: - outputs - seconds - characters - placements - impressions description: > What the rate counts. Reflections observes outputs, seconds and characters itself; placements and impressions come from usage you report. rate: $ref: '#/components/schemas/Money' description: The amount owed for each `per` units. per: type: integer default: 1 description: The rate is for this many units, such as 1000 impressions. revenue_share_bps: type: integer minimum: 0 maximum: 10000 description: Basis points of revenue the license names. minimum: $ref: '#/components/schemas/Money' description: The least the licensee owes, however little is used. schedule: type: string enum: - on_acceptance - monthly - quarterly description: >- When the licensee pays: once on acceptance, each month, or each quarter. Metadata: type: object description: >- Up to 50 keys of your own, each up to 40 characters, values up to 500 characters. Never put personal data here. additionalProperties: type: string maxLength: 500 maxProperties: 50 LicenseRequestStatus: type: string description: >- `sent`: waiting for the talent's side. `signed`: the talent's side signed a license from it. `declined`: the talent's side declined. `withdrawn`: you withdrew it. enum: - sent - signed - declined - withdrawn Problem: type: object description: An RFC 9457 problem detail. Every error has this shape. required: - type - title - status - code - request_id properties: type: type: string format: uri description: A URL for this error, under `https://docs.reflections.ai/errors/`. title: type: string description: A short summary of the error. status: type: integer description: The HTTP status. detail: type: string description: What happened in this request. code: $ref: '#/components/schemas/ErrorCode' description: The stable error code. Branch on it, then on `status`. param: type: string description: The field at fault, as a path such as `use.territories[1]`. request_id: type: string description: > `req_…`, the same value as the `Request-Id` header. Include it when you contact support. doc_url: type: string format: uri description: A link to the documentation for this error. FacetType: type: string description: > `name`: the name in text. `likeness`: face and body in images and video. `voice`: the voice in speech. `twin`: a persona that speaks or writes as the talent. `knowledge`: a Volume of the talent's own words a model may draw on. enum: - name - likeness - voice - twin - knowledge Modality: type: string description: >- What will be generated. `speech` is a voice speaking words; `audio` is any other sound. enum: - image - video - speech - audio - text UseKind: type: string description: > How the talent appears. `depiction`: shown or heard. `impersonation`: speaks or writes as the talent. `endorsement`: implies the talent approves something. `reference`: talked about, without synthesis; needs no license. enum: - depiction - impersonation - endorsement - reference Purpose: type: string enum: - advertising - branded_content - entertainment - editorial - personal - education - political Channel: type: string description: Where the output will appear. enum: - social - web - in_app - streaming - tv - cinema - out_of_home - print - audio - email - retail - games - private Territory: type: string description: An ISO 3166-1 alpha-2 country code, or `WW` for worldwide. pattern: ^([A-Z]{2})$ example: US AdjustmentKind: type: string description: A change the licensee may make to the talent's appearance or context. enum: - reframe - background_extension - lighting - text_overlay - body_and_age - expression - hair - pose - wardrobe - objects - skin_retouch - endorsement Money: type: object required: - amount - currency properties: amount: type: integer description: In the currency's smallest unit, such as cents. currency: type: string pattern: ^[a-z]{3}$ description: ISO 4217, lowercase. ErrorCode: type: string description: A stable error code. See the error code catalog. enum: - invalid_request - parameter_missing - parameter_invalid - unsupported_modality - unsupported_media_type - media_unreadable - version_unsupported - authorization_code_invalid - authentication_required - invalid_api_key - token_invalid - insufficient_scope - account_not_connected - mandate_required - livemode_mismatch - live_not_activated - platform_not_permitted - resource_not_found - idempotency_key_in_use - generation_already_submitted - authorization_consumed - check_not_allowed - check_expired - escalation_closed - license_draft_closed - invalid_state_transition - session_not_active - payload_too_large - idempotency_key_reused - artifact_digest_mismatch - rate_limited - internal_error - service_unavailable - evaluation_timeout headers: RequestId: description: Identifies this request. Include it when you contact support. schema: type: string example: req_8f2k4m6p8r0t2v4x6z8b0d2f4h RateLimit: description: >- Remaining quota and seconds until it resets, as IETF RateLimit header fields. schema: type: string example: '"checks";r=184;t=1' RateLimitPolicy: description: The policy the RateLimit field reports against. schema: type: string example: '"checks";q=200;w=1' RetryAfter: description: Seconds to wait before retrying. schema: type: integer responses: BadRequest: description: The request was malformed or a parameter was invalid. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/parameter_invalid title: A parameter is invalid status: 400 code: parameter_invalid param: use.territories[1] detail: '"UK" is not an ISO 3166-1 alpha-2 code. Use "GB".' request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Unauthorized: description: The key is missing, unknown or revoked. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/invalid_api_key title: The API key is not valid status: 401 code: invalid_api_key request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Forbidden: description: >- The key may not do this, the licensee is not connected, or live mode is not activated for this operation (`live_not_activated`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/account_not_connected title: The licensee has not connected your platform status: 403 code: account_not_connected detail: >- acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account. request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h NotFound: description: No such object for this account. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/resource_not_found title: No such object status: 404 code: resource_not_found request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Conflict: description: >- The request conflicts with the object's state or with a request still running. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/idempotency_key_in_use title: A request with this key is still running status: 409 code: idempotency_key_in_use detail: Retry with the same key after a short wait. request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Unprocessable: description: The request is well formed but cannot be applied. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/idempotency_key_reused title: This key was used for a different request status: 422 code: idempotency_key_reused request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h RateLimited: description: Too many requests. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/rate_limited title: Too many requests status: 429 code: rate_limited request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h ServerError: description: Something failed on our side. Retry with the same idempotency key. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unavailable: description: > Reflections is temporarily unavailable. Do not generate a named talent without a valid authorization. Retry with the same idempotency key. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: SecretKey: type: http scheme: bearer description: > Your secret key, `rk_test_…` or `rk_live_…`, sent as `Authorization: Bearer `. Keep it on your server. Restricted keys carry only the scopes you give them. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.