> ## 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. # Retrieve licensed material > **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). Returns short-lived download URLs for the reference material a license lets the licensee send to a model, such as the reference stills of a likeness. Each item carries its `sha256`; send exactly those bytes. Requires a license whose scope includes `material_access` for this facet. URLs expire after 5 minutes and every download is recorded on the talent's record. Restricted keys need `licenses:read`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /facets/{facet_id}/material 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: /facets/{facet_id}/material: get: tags: - Facets summary: Retrieve licensed material 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). Returns short-lived download URLs for the reference material a license lets the licensee send to a model, such as the reference stills of a likeness. Each item carries its `sha256`; send exactly those bytes. Requires a license whose scope includes `material_access` for this facet. URLs expire after 5 minutes and every download is recorded on the talent's record. Restricted keys need `licenses:read`. operationId: retrieveFacetMaterial parameters: - $ref: '#/components/parameters/ReflectionsVersion' - $ref: '#/components/parameters/ReflectionsAccount' - $ref: '#/components/parameters/FacetId' - name: license in: query required: true description: The license that grants material access. example: lic_ba2q8v1m3n7p4r6s9t0wxyhk5z schema: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ responses: '200': description: The material. 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/FacetMaterial' examples: voice_samples: summary: Voice samples under a voice license value: object: facet_material facet: fct_v1m3n7p4r6s9t0wxyhk5zba2q8 license: lic_ba2q8v1m3n7p4r6s9t0wxyhk5z expires_at: '2026-10-14T16:25:03Z' items: - id: mat_zffz7aewxkb1hpdma9m5w37zb8 kind: voice_sample media_type: audio/wav sha256: >- 4cebb1df0b0005098a1e13cbde6de657fb496d868f34b0ba550f0eb632770118 size: 4585004 duration_ms: 31840 url: >- https://files.reflections.ai/m/mat_zffz7aewxkb1hpdma9m5w37zb8?expires=1791995103&signature=3ce6286e18accc8b0f8c3db4eb17aee9fff44609612 - id: mat_fpzq0ggr5sg91sv7dzrptmrw1n kind: voice_sample media_type: audio/wav sha256: >- ecff26300951e866c0c7a6db07e7dcb0d92d0874305dcb5dd854e35947734078 size: 4091084 duration_ms: 28410 url: >- https://files.reflections.ai/m/mat_fpzq0ggr5sg91sv7dzrptmrw1n?expires=1791995103&signature=c0e46f6a18a2bac3f6bb7eae02f4d2679982ef0045f - id: mat_38p2v2zpjm0sezg5be59w5nww2 kind: voice_sample media_type: audio/wav sha256: >- d643198403c86054c97007384ac6c1ffe93558519c5d23d7721a27c5796da6cc size: 6353324 duration_ms: 44120 url: >- https://files.reflections.ai/m/mat_38p2v2zpjm0sezg5be59w5nww2?expires=1791995103&signature=c34784730b7c58af5b8e5622929bbaac955611b6344 - id: mat_ath88yzbkn61qx00prngj4ymxy kind: voice_sample media_type: audio/wav sha256: >- f368b0a14013c48123544b4fe55b32b73174c560966e33acb01646ccb5fb7330 size: 2845484 duration_ms: 19760 url: >- https://files.reflections.ai/m/mat_ath88yzbkn61qx00prngj4ymxy?expires=1791995103&signature=935302111354709e8f27d08a12e86c755a8f7013e05 - id: mat_vhv37k68efgaqvab2qkyw6wzcj kind: voice_sample media_type: audio/wav sha256: >- 5aff701e270e674472ae1dafee8dad826d612bbb509dc7122deddd9660defcc5 size: 5224364 duration_ms: 36280 url: >- https://files.reflections.ai/m/mat_vhv37k68efgaqvab2qkyw6wzcj?expires=1791995103&signature=2c2b08700888b6dc59d597a56f4a0db84fff6ed1a09 - id: mat_p07weqpc3gn7zas5p8wtnjynen kind: voice_sample media_type: audio/wav sha256: >- 186036056134c4da77b51a4c5820e5918b762310bad0cca7913a9363cafb002c size: 3733964 duration_ms: 25930 url: >- https://files.reflections.ai/m/mat_p07weqpc3gn7zas5p8wtnjynen?expires=1791995103&signature=70b3a88d8e6f01ced2c40eb3eaa5ae75469a754c287 - id: mat_wa5zww7pz1qqy32rpw1nrzyptb kind: voice_sample media_type: audio/wav sha256: >- 6b60e779aabf89f0cdaeba96198506816cdf9eeb5c0935fe66aa4ceb6f78c1c6 size: 5813324 duration_ms: 40370 url: >- https://files.reflections.ai/m/mat_wa5zww7pz1qqy32rpw1nrzyptb?expires=1791995103&signature=b6537d459bf82b5aae3b5409341f472a2e10ca14a0c - id: mat_dmk84vfvnvys94g12h9wrkc7yg kind: voice_sample media_type: audio/wav sha256: >- 7e6371a08f501785586ab6bf9b397ac1f91f98bbe4da598074cb68ce54a13324 size: 3261644 duration_ms: 22650 url: >- https://files.reflections.ai/m/mat_dmk84vfvnvys94g12h9wrkc7yg?expires=1791995103&signature=c62d97161f66a74cc442606d139bea604b5ced6af71 - id: mat_g9s62txt5wajscqskyews8pk4k kind: voice_sample media_type: audio/wav sha256: >- 3a47d9aa9bf8f504813867835a3bd4c556087bc18c23d093c1dad213c7d40264 size: 4825484 duration_ms: 33510 url: >- https://files.reflections.ai/m/mat_g9s62txt5wajscqskyews8pk4k?expires=1791995103&signature=095074067f83cf5ae5efebb1eab8366e539e351a94a - id: mat_ns8wtd4qqq1adaz6vex49s9f27 kind: voice_sample media_type: audio/wav sha256: >- e3039eef0d0a60a54a114ce50a9d3214b31ee75a4222c5977261b155b6dbcf7a size: 4302764 duration_ms: 29880 url: >- https://files.reflections.ai/m/mat_ns8wtd4qqq1adaz6vex49s9f27?expires=1791995103&signature=286161c373b22354115329ed66686f605106c88ebb9 - id: mat_0axxrdtfj5p9f0rcchv6pq8f0m kind: voice_sample media_type: audio/wav sha256: >- 8fc5abd51bea465771aa4f17eb04f1d7d287879f7ee41716c5fbf44f2393b348 size: 5474924 duration_ms: 38020 url: >- https://files.reflections.ai/m/mat_0axxrdtfj5p9f0rcchv6pq8f0m?expires=1791995103&signature=0acf7b5aed66e692bbf5e500c95911832371ebacca5 - id: mat_mxvpmjs64neggm8s4ytea3rkwz kind: voice_sample media_type: audio/wav sha256: >- 359683c5c6d90e4ca0f820be6d0b390474314ab1fba3c31de52ab4da0ef26143 size: 3922604 duration_ms: 27240 url: >- https://files.reflections.ai/m/mat_mxvpmjs64neggm8s4ytea3rkwz?expires=1791995103&signature=a028b4303c8775e43def06193f67404232d4b002f4e obligations: - type: no_training material: voice - type: delete_material material: voice within: P30D '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' security: - SecretKey: - licenses:read x-codeSamples: - lang: bash label: cURL source: > : "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}" curl --fail-with-body --max-time 30 'https://app.reflections.ai/v1/facets/fct_v1m3n7p4r6s9t0wxyhk5zba2q8/material?license=lic_ba2q8v1m3n7p4r6s9t0wxyhk5z' \ -H "Authorization: Bearer $REFLECTIONS_KEY" \ -H "Reflections-Version: 2026-10-15" - lang: typescript label: TypeScript source: > import { env, exit } from "node:process"; const apiKey = env.REFLECTIONS_KEY; if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example"); const response = await fetch("https://app.reflections.ai/v1/facets/fct_v1m3n7p4r6s9t0wxyhk5zba2q8/material?license=lic_ba2q8v1m3n7p4r6s9t0wxyhk5z", { method: "GET", headers: { Authorization: `Bearer ${apiKey}`, "Reflections-Version": "2026-10-15", }, 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 os from urllib.error import HTTPError from urllib.request import Request, urlopen apiKey = os.environ["REFLECTIONS_KEY"] if not apiKey: raise ValueError("Set REFLECTIONS_KEY before running this example") headers = { "Authorization": f"Bearer {apiKey}", "Reflections-Version": "2026-10-15", } request = Request("https://app.reflections.ai/v1/facets/fct_v1m3n7p4r6s9t0wxyhk5zba2q8/material?license=lic_ba2q8v1m3n7p4r6s9t0wxyhk5z", method="GET", headers=headers) 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" "time" ) func main() { apiKey := os.Getenv("REFLECTIONS_KEY") if apiKey == "" { panic("Set REFLECTIONS_KEY before running this example") } request, err := http.NewRequest("GET", "https://app.reflections.ai/v1/facets/fct_v1m3n7p4r6s9t0wxyhk5zba2q8/material?license=lic_ba2q8v1m3n7p4r6s9t0wxyhk5z", nil) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Reflections-Version", "2026-10-15") 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}$ FacetId: name: facet_id in: path required: true description: The facet's ID, `fct_…`. example: fct_v1m3n7p4r6s9t0wxyhk5zba2q8 schema: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ 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 schemas: FacetMaterial: type: object required: - object - facet - license - expires_at - items - obligations properties: object: type: string const: facet_material description: Always `facet_material`. facet: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: The facet the material belongs to. license: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: The license that grants material access, as sent in `license`. expires_at: type: string format: date-time description: When the URLs stop working. items: type: array items: type: object required: - id - kind - media_type - sha256 - size - url properties: id: type: string pattern: ^mat_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier of the item, prefixed `mat_`. kind: type: string enum: - reference_image - reference_video - voice_sample - document description: >- What the item is: a still, a video clip, a voice sample or a document. media_type: type: string description: The item's MIME type, such as `image/jpeg` or `audio/wav`. sha256: $ref: '#/components/schemas/Sha256Hex' description: > SHA-256 of the item's bytes, in hex. Send exactly these bytes to the model. size: type: integer description: Bytes. width: type: integer description: Width in pixels, for images and video. height: type: integer description: Height in pixels, for images and video. duration_ms: type: integer description: Length in milliseconds, for audio and video. url: type: string format: uri description: > Where to download the item until `expires_at`. Every download is recorded on the talent's record. description: >- Every item of the facet's reference material, each with its download URL. obligations: type: array description: What you must do with the material, such as delete it after use. items: $ref: '#/components/schemas/Obligation' Sha256Hex: type: string description: A SHA-256 digest of bytes, as 64 lowercase hex characters. pattern: ^[0-9a-f]{64}$ Obligation: type: object description: >- Something you must do to proceed. Each type uses only the fields listed for it. required: - type properties: type: $ref: '#/components/schemas/ObligationType' description: > The kind of obligation. Treat a type you do not know as unmet: do not generate or deliver. required: type: string enum: - all - sampled description: >- `generation_check`: submit every output, or the sampled share in `sample_rate`. sample_rate: type: number minimum: 0 maximum: 1 description: > `generation_check` with `required: sampled`: the share of outputs to submit, from 0 to 1, chosen at random. reviewer: type: string enum: - talent - representative - reflections description: '`hold_until_release`: who releases each output.' instructions: type: array items: type: string description: '`generation_instructions`: include these in what the model receives.' level: type: string enum: - licensed - brand - scope description: >- `disclosure`: `licensed` says the person's likeness is licensed; `brand` adds who licensed it; `scope` adds the use. text: type: string description: '`disclosure` and `attribution`: the words to show.' placement: type: string enum: - visible - metadata - both description: '`disclosure`: where the label goes.' material: type: string enum: - references - voice - outputs description: '`delete_material` and `no_training`: what the obligation covers.' within: allOf: - $ref: '#/components/schemas/Duration' description: >- The deadline. `delete_material`: counted from the decision. `usage_report`: from the generation's decision or the session's end. units: type: string enum: - outputs - seconds - characters - placements - impressions description: '`usage_report`: the unit to report.' term: $ref: '#/components/schemas/Address' description: The address of the license term the obligation comes from. 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. ObligationType: type: string description: > `generation_check`: submit outputs before delivery. `hold_until_release`: deliver nothing until the reviewer releases it. `draft_watermark`: mark drafts shown while held. `generation_instructions`: pass the instructions to the model. `disclosure`, `attribution`: label the output as stated. `c2pa_manifest`: embed the `c2pa` assertion. `no_training`: never train on the material. `delete_material`: delete it within `within`. `usage_report`: report usage within `within`. enum: - generation_check - hold_until_release - draft_watermark - generation_instructions - disclosure - attribution - c2pa_manifest - no_training - delete_material - usage_report Duration: type: string description: An ISO 8601 duration, such as `PT60S` or `P30D`. example: P30D Address: type: string description: > Where a reason or finding rests, written as an address: `license:/terms.` for a term, `talent:` for a talent's standing boundary. example: license:lic_k5zba2q8v1m3n7p4r6s9t0wxyh/terms.channels 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 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 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.