> ## 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. # List events > **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). Lists events from the last 30 days, newest first, or oldest first after `after`. Restricted keys need `events:read`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /events 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: /events: get: tags: - Events summary: List events 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). Lists events from the last 30 days, newest first, or oldest first after `after`. Restricted keys need `events:read`. operationId: listEvents parameters: - $ref: '#/components/parameters/ReflectionsVersion' - name: type in: query description: >- Only events of this type. Use a prefix with `*`, such as `license.*`. schema: type: string - name: after in: query description: Return events created after this one, oldest first. schema: type: string pattern: ^evt_[0-9a-hjkmnp-tv-z]{26}$ - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of events. 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/EventList' examples: mandate_events: summary: Mandate events, filtered by type value: object: list data: - id: evt_72z7c0jm4ezmm1xzvtmp4j6tm4 object: event type: mandate.ended api_version: '2026-10-15' livemode: true account: null sequence: 2 created_at: '2026-10-29T13:02:11Z' data: object: id: mnd_ww2cs3e4j5tgqqxs7mt7746q4p object: mandate livemode: true talent: tal_4n6p8r0t2v4x6z8b0d2f4h6j8k talent_name: Jonah Reyes representative: acct_6m8n0p2q4r6s8t0v2w4x6y8z0b role: manager powers: - issue_licenses - review_outputs - receive_statements status: ended starts_at: '2026-10-05T15:20:00Z' ends_at: null ended_at: '2026-10-29T13:02:10Z' revocation: rvk_ch7rn89symf3em1rsp31ztxg9b created_at: '2026-10-05T15:20:00Z' previous_attributes: status: active ended_at: null revocation: null - id: evt_td2daf8rebqk19qb6bbfss9j0w object: event type: mandate.created api_version: '2026-10-15' livemode: true account: null sequence: 1 created_at: '2026-10-05T15:20:01Z' data: object: id: mnd_ww2cs3e4j5tgqqxs7mt7746q4p object: mandate livemode: true talent: tal_4n6p8r0t2v4x6z8b0d2f4h6j8k talent_name: Jonah Reyes representative: acct_6m8n0p2q4r6s8t0v2w4x6y8z0b role: manager powers: - issue_licenses - review_outputs - receive_statements status: active starts_at: '2026-10-05T15:20:00Z' ends_at: null ended_at: null revocation: null created_at: '2026-10-05T15:20:00Z' has_more: false next_cursor: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' security: - SecretKey: - events: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/events?limit=10' \ -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/events?limit=10", { 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/events?limit=10", 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/events?limit=10", 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' Limit: name: limit in: query description: Number of objects to return, 1 to 100. schema: type: integer minimum: 1 maximum: 100 default: 20 Cursor: name: cursor in: query description: The `next_cursor` from the previous page. schema: type: string 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: EventList: allOf: - $ref: '#/components/schemas/ListBase' - type: object properties: data: type: array items: $ref: '#/components/schemas/AnyEvent' description: > The events on this page: newest first, or oldest first when you pass `after`. ListBase: type: object required: - object - has_more properties: object: type: string const: list description: Always `list`. has_more: type: boolean description: Whether another page exists. next_cursor: type: - string - 'null' description: Pass as `cursor` to read the next page. AnyEvent: description: >- An event of any type. `type` names it, and `data.object` is the object that type carries. oneOf: - $ref: '#/components/schemas/LicenseEvent' - $ref: '#/components/schemas/LicenseRequestEvent' - $ref: '#/components/schemas/CheckEvent' - $ref: '#/components/schemas/GenerationEvent' - $ref: '#/components/schemas/SessionEvent' - $ref: '#/components/schemas/RevocationEvent' - $ref: '#/components/schemas/ConnectionEvent' - $ref: '#/components/schemas/FacetEvent' - $ref: '#/components/schemas/TalentEvent' - $ref: '#/components/schemas/StatementEvent' - $ref: '#/components/schemas/WebhookEndpointEvent' - $ref: '#/components/schemas/LicenseDraftEvent' - $ref: '#/components/schemas/EscalationEvent' - $ref: '#/components/schemas/MandateEvent' discriminator: propertyName: type mapping: license.issued: '#/components/schemas/LicenseEvent' license.accepted: '#/components/schemas/LicenseEvent' license.revised: '#/components/schemas/LicenseEvent' license.revision_pending: '#/components/schemas/LicenseEvent' license.revision_declined: '#/components/schemas/LicenseEvent' license.suspended: '#/components/schemas/LicenseEvent' license.resumed: '#/components/schemas/LicenseEvent' license.revoked: '#/components/schemas/LicenseEvent' license.expired: '#/components/schemas/LicenseEvent' license.declined: '#/components/schemas/LicenseEvent' license_request.signed: '#/components/schemas/LicenseRequestEvent' license_request.declined: '#/components/schemas/LicenseRequestEvent' check.resolved: '#/components/schemas/CheckEvent' generation.allowed: '#/components/schemas/GenerationEvent' generation.released: '#/components/schemas/GenerationEvent' generation.denied: '#/components/schemas/GenerationEvent' generation.expired: '#/components/schemas/GenerationEvent' session.terminated: '#/components/schemas/SessionEvent' revocation.created: '#/components/schemas/RevocationEvent' revocation.overdue: '#/components/schemas/RevocationEvent' connection.created: '#/components/schemas/ConnectionEvent' connection.revoked: '#/components/schemas/ConnectionEvent' facet.updated: '#/components/schemas/FacetEvent' talent.updated: '#/components/schemas/TalentEvent' statement.issued: '#/components/schemas/StatementEvent' webhook_endpoint.disabled: '#/components/schemas/WebhookEndpointEvent' license_request.created: '#/components/schemas/LicenseRequestEvent' license_draft.signed: '#/components/schemas/LicenseDraftEvent' license_draft.declined: '#/components/schemas/LicenseDraftEvent' escalation.created: '#/components/schemas/EscalationEvent' mandate.created: '#/components/schemas/MandateEvent' mandate.ended: '#/components/schemas/MandateEvent' statement.disputed: '#/components/schemas/StatementEvent' 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. LicenseEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - license.issued - license.accepted - license.revised - license.revision_pending - license.revision_declined - license.suspended - license.resumed - license.revoked - license.expired - license.declined description: The event type, one of the `license.*` event types. data: type: object description: > The license in `object` and, when the event changed it, the old values of the changed fields in `previous_attributes`. properties: object: $ref: '#/components/schemas/License' description: The license as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. LicenseRequestEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - license_request.created - license_request.signed - license_request.declined description: The event type, one of the `license_request.*` event types. data: type: object description: > The license request in `object` and, when the event changed it, the old values of the changed fields in `previous_attributes`. properties: object: $ref: '#/components/schemas/LicenseRequest' description: The license request as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. CheckEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - check.resolved description: Always `check.resolved`. data: type: object description: > The check in `object`, and the fields that changed in `previous_attributes`. properties: object: $ref: '#/components/schemas/Check' description: The check after its escalation was decided or expired. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. GenerationEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - generation.allowed - generation.released - generation.denied - generation.expired description: > `generation.allowed`, `generation.released`, `generation.denied` or `generation.expired`. data: type: object description: > The generation in `object`, and the fields that changed in `previous_attributes`. properties: object: $ref: '#/components/schemas/Generation' description: The generation with its new `status` and `decision`. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. SessionEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - session.terminated description: Always `session.terminated`. data: type: object description: > The session in `object`, and the fields that changed in `previous_attributes`. properties: object: $ref: '#/components/schemas/Session' description: The terminated session. `termination` says why and when. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. RevocationEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - revocation.created - revocation.overdue description: > `revocation.created`: consent narrowed. `revocation.overdue`: a deadline passed before the actions due by it were acknowledged. data: type: object description: The revocation the event is about. properties: object: $ref: '#/components/schemas/Revocation' description: The revocation as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. ConnectionEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - connection.created - connection.revoked description: The event type, `connection.created` or `connection.revoked`. data: type: object description: > The connection in `object` and, when the event changed it, the old values of the changed fields in `previous_attributes`. properties: object: $ref: '#/components/schemas/Connection' description: The connection as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. FacetEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - facet.updated description: Always `facet.updated`. data: type: object description: The facet, and in `previous_attributes` the fields that changed. properties: object: $ref: '#/components/schemas/Facet' description: The facet as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. TalentEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - talent.updated description: Always `talent.updated`. data: type: object description: >- The talent, and in `previous_attributes` the fields that changed. properties: object: $ref: '#/components/schemas/Talent' description: The talent as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. StatementEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - statement.issued - statement.disputed description: > `statement.issued`: a statement is final for its month, or was reissued. `statement.disputed`: the talent's side disputed it. data: type: object description: The statement the event is about. properties: object: $ref: '#/components/schemas/Statement' description: The statement as it was when the event happened. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. WebhookEndpointEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - webhook_endpoint.disabled description: Always `webhook_endpoint.disabled`. data: type: object description: The endpoint, and the fields that changed. properties: object: $ref: '#/components/schemas/WebhookEndpoint' description: The endpoint, now `disabled`. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. LicenseDraftEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - license_draft.signed - license_draft.declined description: '`license_draft.signed` or `license_draft.declined`.' data: type: object description: The draft, and the fields that changed. properties: object: $ref: '#/components/schemas/LicenseDraft' description: The draft after it was signed or declined. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. EscalationEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - escalation.created description: Always `escalation.created`. data: type: object description: The new escalation. properties: object: $ref: '#/components/schemas/EscalationDetail' description: > The escalation as it opened, with the request, use and findings a reviewer needs. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. MandateEvent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: type: type: string enum: - mandate.created - mandate.ended description: '`mandate.created` or `mandate.ended`.' data: type: object description: The mandate and, for `mandate.ended`, the fields that changed. properties: object: $ref: '#/components/schemas/Mandate' description: The mandate when it was created or ended. previous_attributes: type: object description: >- The fields that changed, with their old values. Present on events that change the object. 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 Event: type: object required: - id - object - type - api_version - livemode - sequence - created_at - data properties: id: type: string pattern: ^evt_[0-9a-hjkmnp-tv-z]{26}$ description: Equal to the `webhook-id` header. object: type: string const: event description: Always `event`. type: $ref: '#/components/schemas/EventType' description: What happened, such as `check.resolved`. api_version: type: string description: The API version `data.object` is rendered in. livemode: type: boolean description: '`true` for live events, `false` for test events.' account: type: - string - 'null' pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: >- The connected licensee the event concerns, when it is not your own account. sequence: type: integer description: >- Increases by one with each event about the same object. Ignore an event whose sequence is lower than one you have processed. created_at: type: string format: date-time description: When the event happened. data: type: object description: >- The object the event is about and, for a change, the fields that changed. required: - object properties: object: type: object description: The object as it was when the event happened. previous_attributes: type: object description: The fields that changed, with their old values. License: type: object required: - id - object - livemode - status - talent - licensee - handle - current_revision - revision_number - scope - created_at properties: id: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier for the license, `lic_…`. object: type: string const: license description: Always `license`. livemode: type: boolean description: '`true` for a live-mode license, `false` for a test-mode one.' status: $ref: '#/components/schemas/LicenseStatus' description: > Where the license is in its life. Checks are decided on its terms only while it is `active`; under every other status they deny. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent who granted the license. licensee: type: - string - 'null' pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account that holds the license and answers for every use made under it. Null on a `pending_acceptance` license its talent reads before anyone accepts the invitation. issued_by: type: object description: Who signed the first revision. properties: party: type: string enum: - talent - representative description: > `talent` when the talent signed, or `representative` when a representative with `issue_licenses` signed for them. account: type: - string - 'null' pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The representative's account. `null` when the talent signed. mandate: type: - string - 'null' pattern: ^mnd_[0-9a-hjkmnp-tv-z]{26}$ description: The mandate a representative signed under. draft: type: - string - 'null' pattern: ^ldr_[0-9a-hjkmnp-tv-z]{26}$ description: The draft the license was signed from, if any. handle: type: string pattern: ^[0-9BCDFGHJKMNPQRSTVWXYZ]{6}$ description: >- A six-character name for the license that people can read aloud, such as `K7Q4M2`. current_revision: type: string pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: >- The revision in force. While the license is `pending_acceptance`, the first revision, waiting to be accepted. revision_number: type: integer minimum: 1 description: The `number` of `current_revision`, starting at 1. pending_revision: type: - string - 'null' pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: > A new revision the talent's side signed, such as a change the licensee requested, an amendment or a renewal, waiting for the licensee to accept it at `acceptance_url`. `current_revision` stays in force until then. terms_digest: $ref: '#/components/schemas/Digest' description: > The digest of the current revision's signed `terms`. Checks, authorizations and receipts decided under that revision carry the same value. A live read returns the digest of the full signed terms, not a digest of the partial `scope`; live revision retrieval and live decision endpoints remain planned. scope: $ref: '#/components/schemas/LicenseScope' description: > The terms of `current_revision` in normalized form. A pending revision does not change it until the licensee accepts. acceptance_url: type: - string - 'null' format: uri description: >- The hosted page where the licensee reads and accepts the license, or its `pending_revision`. Present while `pending_acceptance`, and while a revision is pending. accepted_at: type: - string - 'null' format: date-time description: When the licensee accepted the license. `null` until then. suspended_at: type: - string - 'null' format: date-time description: >- When the current suspension began. `null` unless the license is `suspended`. revoked_at: type: - string - 'null' format: date-time description: When the license was revoked. `null` unless it is `revoked`. declined_at: type: - string - 'null' format: date-time description: >- When the licensee declined the license. `null` unless it is `declined`. metadata: $ref: '#/components/schemas/Metadata' description: Key-value pairs stored on the license. created_at: type: string format: date-time description: When the talent's side signed the first revision. 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. Check: type: object required: - id - object - livemode - status - decision - talent - use - reasons - obligations - request_digest - created_at properties: id: type: string pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$ description: The check's ID, `chk_` followed by 26 characters. object: type: string const: check description: Always `check`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' status: $ref: '#/components/schemas/CheckStatus' description: > Where the check is now. An `allow` can later become `consumed`, `expired` or `cancelled`; an `escalate` ends `allowed`, `denied` or `cancelled`. decision: description: > `allow`, `deny` or `escalate`. An escalated check's decision becomes `allow` or `deny` when a person decides or the escalation expires. Null while `status` is `checking`. oneOf: - $ref: '#/components/schemas/Decision' - type: 'null' talent: type: array items: $ref: '#/components/schemas/CheckTalent' description: > Each protected talent the request invokes, with that talent's own decision and license. Empty when none is found. use: $ref: '#/components/schemas/Use' description: The use the check decided, as you sent it. reasons: type: array items: $ref: '#/components/schemas/Reason' description: Why the use was denied or escalated. Empty on `allow`. obligations: type: array items: $ref: '#/components/schemas/Obligation' description: What you must do to proceed. Empty unless `decision` is `allow`. authorization: description: > Proof of the `allow`. Pass `token` to the tool or provider that generates. Null unless `decision` is `allow`. oneOf: - $ref: '#/components/schemas/Authorization' - type: 'null' escalation: description: > The escalation, when the check is `escalated` or was decided by a person. When several talent are escalated, each has their own, named in `talent[].escalation`. While the check is open, this field shows the open one that expires first, so its `expires_at` is when the check becomes `deny`. Once decided, it shows the one that decided: the first `deny` or expiry, or the last `allow`. The others still open are then `cancelled`. oneOf: - $ref: '#/components/schemas/Escalation' - type: 'null' remedy: description: > What would change a `deny`. Null for other decisions, and when no change can help, as with `talent_prohibits`. oneOf: - $ref: '#/components/schemas/Remedy' - type: 'null' request_digest: allOf: - $ref: '#/components/schemas/Digest' description: >- Digest of the inputs, use and execution this check decided. Without `reuse`, the authorization covers only this request; with `reuse`, it also covers later generations of the same use, talent, execution and end user. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account that holds the license: the licensee named in `Reflections-Account`, or your own account under a platform license. platform: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The account that ran the check. session: type: - string - 'null' pattern: ^ses_[0-9a-hjkmnp-tv-z]{26}$ description: > The session this check started, for a check run by `POST /v1/sessions`. Null otherwise. receipt: type: - string - 'null' pattern: ^rcpt_[0-9a-hjkmnp-tv-z]{26}$ description: > The receipt that records the decision. Null until an escalated check is decided. metadata: $ref: '#/components/schemas/Metadata' description: Your metadata from the request. created_at: type: string format: date-time description: When the check was created. Generation: type: object required: - id - object - livemode - status - assurance - created_at properties: id: type: string pattern: ^gen_[0-9a-hjkmnp-tv-z]{26}$ description: The generation's ID, `gen_` followed by 26 characters. object: type: string const: generation description: Always `generation`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' check: type: - string - 'null' pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$ description: >- The check the output was made under. Null for an output made in a session. session: type: - string - 'null' pattern: ^ses_[0-9a-hjkmnp-tv-z]{26}$ description: >- The session the output was made in. Null for an output made under a check. candidate_index: type: - integer - 'null' description: > Which of the check's candidates this is, from 0. Null under `reuse` and for an output made in a session. status: $ref: '#/components/schemas/GenerationStatus' description: Where the output is. Deliver only on `allowed` or `released`. decision: description: > `allow`, `deny`, or `escalate` while a reviewer must release the output. Null while `status` is `checking`. oneOf: - $ref: '#/components/schemas/Decision' - type: 'null' artifact: type: - object - 'null' description: The output that was checked. properties: file: type: - string - 'null' description: > The file the output was uploaded as. Null when it was sent as `url` or `data`. sha256: $ref: '#/components/schemas/Sha256Hex' description: > The SHA-256 of the checked bytes. The receipt carries it as `artifact_sha256`. media_type: type: string description: The output's media type, such as `image/png`. duration_ms: type: - integer - 'null' description: Length in milliseconds, for audio and video. Null otherwise. execution: $ref: '#/components/schemas/Execution' description: The run that made the output, as you stated it. findings: type: array items: $ref: '#/components/schemas/Finding' description: Each rule checked on the bytes, with its result. unchecked_terms: type: array items: $ref: '#/components/schemas/Address' description: > Addresses of rules the talent wrote that could not be checked on these bytes. They do not withhold the output. reasons: type: array items: $ref: '#/components/schemas/Reason' description: Why the output was denied or expired. Empty otherwise. obligations: type: array items: $ref: '#/components/schemas/Obligation' description: > What you must do with this output, such as embed `c2pa` and show the disclosure, or keep it private while `held`. escalation: description: >- The release review, when a person must release the output. Null otherwise. oneOf: - $ref: '#/components/schemas/Escalation' - type: 'null' assurance: type: string enum: - observed - attested description: >- `observed`: Reflections checked these bytes. `attested`: Reflections recorded what you stated without checking it. receipt: type: - string - 'null' pattern: ^rcpt_[0-9a-hjkmnp-tv-z]{26}$ description: > The receipt that records the decision. Null while the output is `checking` or `held`, and after a withdrawal from review. c2pa: description: > The assertion to embed in the output's C2PA manifest before you deliver it. Null unless `decision` is `allow`. oneOf: - $ref: '#/components/schemas/C2paAssertion' - type: 'null' watermark: type: - object - 'null' description: The watermark you registered on the generation. Null if none. properties: algorithm: type: string description: The watermarking method you used. id: type: string description: The watermark's identifier, as embedded in the output. metadata: $ref: '#/components/schemas/Metadata' description: Your metadata from the request. created_at: type: string format: date-time description: When the output was submitted. decided_at: type: - string - 'null' format: date-time description: >- When the output was allowed, released, denied or expired. Null otherwise. Session: type: object required: - id - object - livemode - status - check - created_at properties: id: type: string pattern: ^ses_[0-9a-hjkmnp-tv-z]{26}$ description: The session's ID, `ses_` followed by 26 characters. object: type: string const: session description: Always `session`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' status: type: string enum: - active - denied - ended - terminated description: > `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. check: type: string pattern: ^chk_[0-9a-hjkmnp-tv-z]{26}$ description: The check Reflections ran on the session's inputs when it started. license: type: - string - 'null' pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: The license the session runs under. Null when none applies. talent: type: array items: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the session covers. token: type: - string - 'null' description: >- A JWS with `typ` `tlp-session+jwt`. Null when the session is not active. expires_at: type: - string - 'null' format: date-time description: > When the current token expires, 5 minutes after it was issued. Null when the session is not active. renew_every: $ref: '#/components/schemas/Duration' description: 'How often to renew the token: `PT60S`.' sampling: $ref: '#/components/schemas/Sampling' description: Which samples to submit, and how often. obligations: type: array items: $ref: '#/components/schemas/Obligation' description: What you must do for the whole session, such as show the disclosure. reasons: type: array items: $ref: '#/components/schemas/Reason' description: Why the session was denied. Empty otherwise. stream_url: type: - string - 'null' format: uri description: > The session stream's WebSocket URL. Stay connected to receive `session.terminated`. Null when the session is denied. termination: type: - object - 'null' description: > Why and when Reflections ended the session. Null unless `status` is `terminated`. The session stream's `session.terminated` message carries the same fields. required: - reason - sentence - revocation - sample - at properties: reason: $ref: '#/components/schemas/ReasonCode' description: >- A reason code, such as `license_revoked` or `prohibited_custom_term`. sentence: type: string description: >- The reason in the license's own words. Show it to your user as written. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent it concerns, when the session has several. term: $ref: '#/components/schemas/Address' description: The license term or standing rule it rests on, as an address. revocation: type: - string - 'null' pattern: ^rvk_[0-9a-hjkmnp-tv-z]{26}$ description: >- The revocation that ended the session, for `license_revoked` and `license_suspended`. sample: type: - string - 'null' pattern: ^smp_[0-9a-hjkmnp-tv-z]{26}$ description: The sample that was denied, if one was. at: type: string format: date-time description: >- When Reflections ended the session. Report usage up to this time. ended_at: type: - string - 'null' format: date-time description: > When you ended the session with `POST /v1/sessions/{session_id}/end`. Null until then. metadata: $ref: '#/components/schemas/Metadata' description: Your metadata from the request. created_at: type: string format: date-time description: When the session started. Revocation: type: object required: - id - object - livemode - scope - targets - status - initiated_by - effective_at - required_actions - acknowledge_by - acknowledgements - created_at properties: id: type: string pattern: ^rvk_[0-9a-hjkmnp-tv-z]{26}$ description: > The revocation's ID. Pass it as `after` to read the revocations created after it. object: type: string const: revocation description: Always `revocation`. livemode: type: boolean description: '`true` in live mode, `false` for an object created with a test key.' scope: type: string enum: - license - facet - mandate - talent description: >- `license`: one license. `facet`: a facet withdrawn, which narrows every license that covers it. `mandate`: a representative's authority ended. `talent`: consent withdrawn everywhere. targets: type: object description: What the revocation cuts. Which fields are set depends on `scope`. properties: talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent whose consent narrowed. Set at every scope. licenses: type: array items: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: > The licenses cut: the revoked license, every license that covers a withdrawn facet, or the licenses the talent revoked with an ended mandate. facets: type: array items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: > The withdrawn facets, for `scope` `facet`. Other scopes may list facets of the cut licenses that need action, such as one with a copy in `provider_copies`. mandate: type: - string - 'null' pattern: ^mnd_[0-9a-hjkmnp-tv-z]{26}$ description: The ended mandate, for `scope` `mandate`. Null at other scopes. status: $ref: '#/components/schemas/RevocationStatus' description: > `pending_acknowledgement` until every required action is acknowledged, then `acknowledged`, or `overdue` if a deadline passes first. initiated_by: type: string enum: - talent - representative - reflections description: > Who revoked: the talent in the Talent Portal, a representative whose mandate has `revoke`, or Reflections. for_cause: type: boolean description: Revoked for a breach. Only then can `withdraw` apply. cause: type: - string - 'null' description: >- For a revocation for cause, the breach, as whoever revoked it stated it. note: type: - string - 'null' description: A note from whoever revoked it. effective_at: type: string format: date-time description: When the revocation took effect. `acknowledge_by` is 24 hours later. post_revocation: type: object description: > What happens to outputs released before `effective_at`, copied from the license's `post_revocation` term. properties: policy: type: string enum: - retain - cease_distribution - withdraw description: > `retain`: released outputs stay usable within their scope and window. `cease_distribution`: no new placements. `withdraw`: take them down by `withdraw_by`; only when `for_cause` is `true`. withdraw_by: type: - string - 'null' format: date-time description: > When released outputs must be down and `withdraw_outputs` acknowledged. Null unless `policy` is `withdraw`. required_actions: type: array items: $ref: '#/components/schemas/RevocationAction' description: What every platform that used the targets must do and acknowledge. provider_copies: type: array description: Copies at model providers you must delete. items: type: object properties: facet: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: The facet the copy was made from. provider: type: string description: The model provider that holds the copy. external_id: type: string description: > The copy's ID at the provider, such as a voice ID. Delete the copy by this ID. affected: type: object description: What the revocation cut, at `effective_at`. properties: checks_denied: type: integer description: > Checks pending or escalated at `effective_at`, now denied with `license_revoked`. generations_denied: type: integer description: Held outputs that can no longer be released. sessions_terminated: type: integer description: Live sessions ended, each with `session.terminated`. released_outputs: type: integer description: Released outputs now governed by `post_revocation`. acknowledge_by: type: string format: date-time description: > When every required action except `withdraw_outputs` must be acknowledged: 24 hours after `effective_at`. acknowledgements: type: array items: type: object required: - account - actions - acknowledged_at properties: account: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The platform that acknowledged. actions: type: array items: $ref: '#/components/schemas/RevocationAction' description: The actions this acknowledgement attests were done. deleted_copies: type: array items: type: object properties: provider: type: string description: The model provider that held the copy. external_id: type: string description: The copy's ID at the provider, from `provider_copies`. deleted_at: type: string format: date-time description: When the platform deleted the copy. description: The provider copies the platform deleted. note: type: - string - 'null' description: The platform's note, as sent. acknowledged_at: type: string format: date-time description: When Reflections received the acknowledgement. description: > Each acknowledgement a platform sent, in the order received. Shown on the talent's record. created_at: type: string format: date-time description: When Reflections recorded the revocation. Connection: type: object required: - id - object - livemode - status - licensee - platform - scopes - licenses - created_at properties: id: type: string pattern: ^con_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier for the connection, `con_…`. object: type: string const: connection description: Always `connection`. livemode: type: boolean description: '`true` for a live-mode connection, `false` for a test-mode one.' status: type: string enum: - active - revoked description: > `active` while the platform may act for the licensee. `revoked` once the licensee, the platform or Reflections ended it. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account whose licenses the platform may use. Send it in `Reflections-Account`. licensee_name: type: string description: The licensee's account name. platform: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The platform account that acts for the licensee. platform_name: type: string description: >- The platform's `display_name`, as the licensee saw it when approving. scopes: type: array items: type: string enum: - talent:read - licenses:read - license_requests:write - files:write - checks:write - generations:write - sessions:write - revocations:write - usage:write - statements:read description: > What the platform may do for the licensee, as approved through OAuth. A call that needs a scope not listed fails with `403 account_not_connected`. licenses: type: object description: Which of the licensee's licenses the platform may use. properties: mode: type: string enum: - all - listed description: > `all`: every license the licensee holds. `listed`: only the licenses in `ids`. ids: type: array items: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: > The licenses the platform may use when `mode` is `listed`. Empty for `all`. revoked_by: type: - string - 'null' enum: - licensee - platform - reflections - null description: Who ended the connection. `null` while it is `active`. revoked_at: type: - string - 'null' format: date-time description: > When the connection ended. From then, calls for the licensee fail with `account_not_connected`. `null` while it is `active`. created_at: type: string format: date-time description: When the licensee approved the connection. Facet: type: object required: - id - object - livemode - talent - type - label - status - modalities - created_at properties: id: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: > Unique identifier, prefixed `fct_`. Send it in a check's `facet` to pick one of several facets of a type. object: type: string const: facet description: Always `facet`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent this facet belongs to. type: $ref: '#/components/schemas/FacetType' description: The part of the talent's identity the facet covers. label: type: string description: The talent's name for it, such as "Speaking voice". status: $ref: '#/components/schemas/FacetStatus' description: > Whether the facet can be licensed. A withdrawal also arrives as a revocation with `scope: "facet"`. modalities: type: array description: What this facet can be used to generate. items: $ref: '#/components/schemas/Modality' material: type: - object - 'null' description: >- Reference material behind the facet. Download it through the material endpoint. properties: items: type: integer minimum: 0 description: How many items of reference material the facet holds. updated_at: type: string format: date-time description: When the material last changed. provider_bindings: type: array items: $ref: '#/components/schemas/ProviderBinding' description: > Copies of the facet held at model providers. Shown only to that provider and to licensees whose license includes `material_access` for the facet. created_at: type: string format: date-time description: When the facet was created. updated_at: type: string format: date-time description: When the facet's material, status or provider bindings last changed. Talent: type: object required: - id - object - livemode - name - aliases - status - verification - protection - posture - facets - created_at properties: id: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier, prefixed `tal_`. object: type: string const: talent description: Always `talent`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' name: type: string description: The name the talent confirmed. aliases: type: array description: >- Other names the talent confirmed, such as a stage name or a transliteration. items: type: string status: type: string enum: - active - withdrawn description: >- `withdrawn`: the talent withdrew consent everywhere. Every check denies with `license_revoked` or `talent_prohibits`. verification: type: object description: > Proves a real adult controls this talent's account and signed their licenses. It does not prove who owns every right in the name. required: - verified properties: verified: type: boolean description: > Whether Reflections verified that a real adult controls this talent's account. method: type: - string - 'null' enum: - id_document - representative - null description: > How the talent was verified: with an identity document, or through a representative. `null` when not verified. verified_at: type: - string - 'null' format: date-time description: When the talent was verified. `null` when not verified. protection: type: object description: How references are matched to this talent. required: - references properties: references: type: boolean description: >- Reference images and voice samples sent with a check are matched against this talent's face and voice. modalities: type: array items: $ref: '#/components/schemas/Modality' description: >- The modalities in which reference media is matched against this talent. posture: $ref: '#/components/schemas/Posture' description: The talent's standing public answers for uses with no license. representation: type: array items: $ref: '#/components/schemas/Representation' description: > Accounts with a mandate to act for the talent, with each one's `role` and `powers`. facets: type: array items: $ref: '#/components/schemas/FacetSummary' description: > Each facet's `id`, `type`, `label` and `status`. Retrieve a facet for the rest. hcs_subject_id: type: - string - 'null' description: >- The talent's subject ID in the Human Consent Registry, when registered there. profile_url: type: string format: uri description: The talent's public page. created_at: type: string format: date-time description: When the talent's record was created. updated_at: type: string format: date-time description: When the talent last changed. Statement: type: object required: - id - object - livemode - license - talent - licensee - status - period - currency - lines - amount_due - amount_paid - reconciliation - created_at properties: id: type: string pattern: ^stmt_[0-9a-hjkmnp-tv-z]{26}$ description: The statement's ID. Record, confirm and dispute payments against it. object: type: string const: statement description: Always `statement`. livemode: type: boolean description: > `true` in live mode, `false` in test mode, where statements are generated daily. license: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: > The license the statement covers. Each statement covers one license for one month. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the licensee owes. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The account that holds the license and pays the talent's payee. status: $ref: '#/components/schemas/StatementStatus' description: > `open` while the month runs, then `issued`. `paid` once confirmed payments reach `amount_due`, or `disputed` while the talent's side disputes it. period: type: object description: The month the statement covers. properties: start: type: string format: date-time description: The start of the period, inclusive. end: type: string format: date-time description: 'The end of the period, exclusive: the start of the next month.' currency: type: string pattern: ^[a-z]{3}$ description: The ISO 4217 code, lowercase, of every amount on the statement. lines: type: array items: type: object properties: description: type: string description: The line's label, as the statement document shows it. units: $ref: '#/components/schemas/UsageUnits' description: The unit counted, from the license's `compensation`. reported: type: number description: Units you reported. observed: type: number description: Units Reflections recorded from checks and generations. billable: type: number description: The greater of reported and observed. rate: description: > The license's rate for this unit. Null for a line without a per-unit rate. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' amount: type: integer description: '`billable` at `rate`, in the currency''s smallest unit.' description: One line per unit the license bills. amount_due: type: integer description: > What the licensee owes for the period under the license's `compensation`, in the currency's smallest unit. amount_paid: type: integer description: The total of `payments`, in the currency's smallest unit. reconciliation: type: object description: How the units reported compare with the units Reflections observed. properties: result: type: string enum: - matched - under_reported - over_reported description: > `matched`: reported and observed agree. `under_reported`: Reflections observed more than was reported. `over_reported`: more was reported than observed. detail: type: - string - 'null' description: The difference, in words. Null when `matched`. payments: type: array items: type: object properties: id: type: string pattern: ^pay_[0-9a-hjkmnp-tv-z]{26}$ description: >- The payment's ID. The talent's side passes it to Confirm a payment. amount: type: integer description: In the currency's smallest unit. paid_at: type: string format: date-time description: When the licensee says it paid. method: type: string enum: - bank_transfer - card - check - other description: How the licensee says it paid. reference: type: - string - 'null' description: > The licensee's payment reference, such as a wire ID. Null if it gave none. confirmed_at: type: - string - 'null' format: date-time description: When the talent's side confirmed receipt. description: >- Payments the licensee recorded against the statement, in the order recorded. dispute: type: - object - 'null' description: Present while the talent's side disputes the statement. properties: reason: type: string description: Why the talent's side disputes the statement, as written. disputed_at: type: string format: date-time description: When the talent's side disputed the statement. due_at: type: - string - 'null' format: date-time description: When payment is due. Null while `open`. issued_at: type: - string - 'null' format: date-time description: > When the statement was issued, or last reissued after a dispute. Null while `open`. document_url: type: - string - 'null' format: uri description: The statement as a document a person reads. Null while `open`. created_at: type: string format: date-time description: When the statement opened, at the start of its period. WebhookEndpoint: type: object required: - id - object - livemode - url - events - status - api_version - created_at properties: id: type: string pattern: ^we_[0-9a-hjkmnp-tv-z]{26}$ description: The endpoint's ID, `we_…`. object: type: string const: webhook_endpoint description: Always `webhook_endpoint`. livemode: type: boolean description: > `true` for an endpoint created with a live key, which receives only live events. `false` for one created with a test key, which receives only test events. url: type: string format: uri description: The HTTPS URL events are sent to. events: type: array items: anyOf: - $ref: '#/components/schemas/EventType' - type: string const: '*' description: Every event type. description: > The event types sent to this endpoint. `["*"]` sends every type, including types added later. description: type: - string - 'null' description: Your label for the endpoint. `null` when you set none. status: type: string enum: - enabled - disabled description: > `enabled`, or `disabled` after every delivery failed for 5 days. Re-enable a disabled endpoint by updating it with `status: enabled`. disabled_reason: type: - string - 'null' description: Why Reflections disabled the endpoint. `null` while `enabled`. api_version: type: string description: > The version events are rendered in. Set when the endpoint is created; it cannot be changed. connected: type: boolean description: > Whether the endpoint also receives events about connected licensees' objects. Those events carry the licensee's ID in `account`. secret: type: - string - 'null' description: >- `whsec_…`. Returned only when the endpoint is created or its secret rotated. metadata: $ref: '#/components/schemas/Metadata' description: Keys and values of your own. created_at: type: string format: date-time description: When the endpoint was created. LicenseDraft: type: object required: - id - object - livemode - status - kind - talent - licensee - scope - terms_digest - signer - created_by - expires_at - created_at properties: id: type: string pattern: ^ldr_[0-9a-hjkmnp-tv-z]{26}$ description: The draft's ID, `ldr_…`. object: type: string const: license_draft description: Always `license_draft`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' status: $ref: '#/components/schemas/LicenseDraftStatus' description: > `open` until the signer signs or declines it, it is discarded, or it passes `expires_at`. kind: type: string enum: - issue - change_request - amend - renew description: > What signing creates. `issue`: a new license. `change_request`: a new revision answering a request of kind `change`. `amend`: new terms for `license`. `renew`: a new window for `license`. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the license is for. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account that holds or will hold the license. It accepts what is signed on its hosted acceptance page. license: type: - string - 'null' pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: >- The license this draft changes, or, once an `issue` draft is signed, the license it became. license_request: type: - string - 'null' pattern: ^lrq_[0-9a-hjkmnp-tv-z]{26}$ description: The license request this draft answers. `null` when it answers none. scope: $ref: '#/components/schemas/LicenseScope' description: >- The full terms the signer will see, with the current revision's values filled in. terms_digest: $ref: '#/components/schemas/Digest' description: > The `terms_digest` the revision will carry if it is signed as drafted. Compare it with the signed revision's to see whether the signer changed anything. signer: type: string enum: - talent - representative description: > Who signs. `talent`: the talent, in the Talent Portal. `representative`: a person at your account with `issue_licenses`. signing_url: type: - string - 'null' format: uri description: >- The Talent Portal page where the signer reads and signs the draft with a passkey. Present while `open`. signed_as_drafted: type: - boolean - 'null' description: Once signed, `false` when the signer changed terms before signing. license_revision: type: - string - 'null' pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: The revision that signing created. decision_note: type: - string - 'null' description: The signer's note when they declined. note: type: - string - 'null' description: >- Shown to the licensee on the acceptance page. `null` when you sent none. created_by: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The representative account that prepared the draft. expires_at: type: string format: date-time description: > When the draft can no longer be signed. 30 days after it was created, unless you set an earlier time. signed_at: type: - string - 'null' format: date-time description: When the signer signed. `null` unless `signed`. declined_at: type: - string - 'null' format: date-time description: When the signer declined. `null` unless `declined`. metadata: $ref: '#/components/schemas/Metadata' description: Keys and values of your own. created_at: type: string format: date-time description: When you created the draft. EscalationDetail: title: Escalation description: An escalation with the request, use and findings a reviewer needs. allOf: - $ref: '#/components/schemas/Escalation' - type: object required: - object - livemode - subject - talent - license - licensee - platform - use - request_digest - created_at properties: object: type: string const: escalation description: Always `escalation`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' subject: type: object description: What waits on the decision. required: - object - id properties: object: type: string enum: - check - generation description: >- `check` for an escalated check, `generation` for a held output. id: type: string description: The check (`chk_…`) or generation (`gen_…`) ID. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: > The talent whose side decides. When a check escalates for several talent, each has their own escalation. license: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: The license the request was checked under. license_revision: type: string pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: The revision of `license` the request was checked against. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The account that holds `license`. licensee_name: type: string description: The licensee's account name. platform: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The platform that ran the check or submitted the output. platform_name: type: string description: The platform's account name. use: $ref: '#/components/schemas/Use' description: The use the platform asked for on the check. inputs: type: array description: > 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. items: $ref: '#/components/schemas/Input' reasons: type: array description: What raised the question, with the talent's term. items: $ref: '#/components/schemas/Reason' findings: type: array description: For a held output, what Reflections recorded on its bytes. items: $ref: '#/components/schemas/Finding' artifact: type: - object - 'null' description: For a held output, the clean bytes to review. properties: sha256: $ref: '#/components/schemas/Sha256Hex' description: > SHA-256 of the held output's bytes, as on the generation's `artifact`. media_type: type: string description: The output's media type, such as `image/png`. url: type: string format: uri description: Opens for 15 minutes. request_digest: $ref: '#/components/schemas/Digest' description: > The `request_digest` of the check. Allowing an escalated check covers exactly this request. review_url: type: - string - 'null' format: uri description: >- The Talent Portal page where a person with authority reviews it and decides. Present while `open`. decision: type: - string - 'null' enum: - allow - deny - null description: > The decision a person recorded, `allow` or `deny`. `null` until one is recorded. decided_by: type: - object - 'null' description: Who resolved it. properties: party: type: string enum: - talent - representative - reflections description: > `talent` when the talent decided, `representative` when a representative recorded the decision, `reflections` for an escalation under a platform license. account: type: - string - 'null' pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The representative's account. `null` when the talent or Reflections decided. name: type: string description: >- The person who decided, as recorded on the talent's audit record. created_at: type: string format: date-time description: When the check escalated or the output was held. Mandate: type: object description: >- A talent's appointment of your account as their representative, with the powers they chose. required: - id - object - livemode - talent - talent_name - representative - role - powers - status - starts_at - created_at properties: id: type: string pattern: ^mnd_[0-9a-hjkmnp-tv-z]{26}$ description: The mandate's ID, `mnd_…`. object: type: string const: mandate description: Always `mandate`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent who appointed you. talent_name: type: string description: The talent's name, for display. representative: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: Your account. role: type: string enum: - agency - manager - estate - union - legal description: > The kind of representative the talent appointed you as. `legal` is legal counsel. powers: type: array description: > `issue_licenses`: draft licenses and answer license requests. `review_outputs`: resolve escalations and release held outputs. `revoke`: suspend, resume and revoke licenses. `receive_statements`: read statements, confirm payments and dispute statements. items: type: string enum: - issue_licenses - review_outputs - revoke - receive_statements status: type: string enum: - active - ended description: > `active` while you may act for the talent. `ended` once the talent ended it or `ends_at` passed. starts_at: type: string format: date-time description: When you may start acting for the talent. ends_at: type: - string - 'null' format: date-time description: When the mandate ends on its own, if the talent set an end. ended_at: type: - string - 'null' format: date-time description: When the mandate ended. `null` while `active`. revocation: type: - string - 'null' pattern: ^rvk_[0-9a-hjkmnp-tv-z]{26}$ description: >- The revocation with `scope` `mandate` that ended it, when the talent ended it. created_at: type: string format: date-time description: When the talent appointed you in the Talent Portal. EventType: type: string enum: - license.issued - license.accepted - license.revised - license.revision_pending - license.revision_declined - license.suspended - license.resumed - license.revoked - license.expired - license.declined - license_request.created - license_request.signed - license_request.declined - license_draft.signed - license_draft.declined - check.resolved - escalation.created - generation.allowed - generation.released - generation.denied - generation.expired - session.terminated - revocation.created - revocation.overdue - connection.created - connection.revoked - facet.updated - talent.updated - statement.issued - statement.disputed - mandate.created - mandate.ended - webhook_endpoint.disabled LicenseStatus: type: string description: > `pending_acceptance`: signed on the talent's side, waiting for the licensee. `scheduled`: accepted, window not started. `active`: in force. `suspended`: paused by the talent or a representative. `expired`: the window ended. `declined`: the licensee declined it. `revoked`: ended by the talent or a representative. `void`: voided in the issuing system; the license grants no use. The test-mode status filter does not accept `void`. enum: - pending_acceptance - scheduled - active - suspended - expired - declined - revoked - void Digest: type: string description: A SHA-256 digest, `sha256:` followed by 64 lowercase hex characters. pattern: ^sha256:[0-9a-f]{64}$ LicenseScope: type: object description: > The license's terms in normalized, snake_case form. Generated from the signed `terms`; when they disagree, `terms` wins. Live license reads currently return only `window`, `required_attributes`, `release_policy` and `final_deliverables`, plus `external_creation` only when that grant is explicitly signed. Omitted fields grant nothing; this partial projection is not the complete signed document. properties: facets: type: array items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: > The facets the license covers, by ID. A use of any other facet denies with `facet_not_licensed`. modalities: type: array items: $ref: '#/components/schemas/Modality' description: > What may be generated under the license. Any other modality denies with `modality_not_licensed`. kinds: type: array items: $ref: '#/components/schemas/UseKind' description: > How the talent may appear in outputs. Any other kind denies with `kind_not_licensed`. purposes: type: array items: $ref: '#/components/schemas/Purpose' description: > What outputs may be used for. Any other purpose denies with `purpose_not_licensed`. commercial: type: boolean description: > Whether commercial use is licensed. When `false`, a commercial use denies with `commercial_use_not_licensed`. channels: type: array items: $ref: '#/components/schemas/Channel' description: > Where outputs may appear. A use that names any other channel denies with `channel_not_licensed`. From `terms.channels`. territories: type: array items: $ref: '#/components/schemas/Territory' description: > Where outputs may appear, as ISO 3166-1 alpha-2 codes or `WW`. A use that names any other territory denies with `territory_not_licensed`. From `terms.territories`. window: type: object description: > When the license is in force. From `terms.startsAt`, `terms.endsAt` and `terms.windowTimeZone`. properties: starts_at: type: string format: date-time description: > When the license comes into force. Before it, checks deny with `window_not_started`. ends_at: type: string format: date-time description: > When the license ends. From then, checks deny with `window_ended` and the license is `expired`. time_zone: type: - string - 'null' description: The IANA time zone the window's days were signed in. adjustments: type: object description: Each adjustment and whether it is allowed. From `terms.adjustments`. additionalProperties: false properties: reframe: type: boolean description: '`true` allows cropping or reframing the composition.' background_extension: type: boolean description: '`true` allows extending or replacing the background.' lighting: type: boolean description: '`true` allows changing the lighting.' text_overlay: type: boolean description: '`true` allows adding text over the output.' body_and_age: type: boolean description: '`true` allows changing the talent''s body or apparent age.' expression: type: boolean description: '`true` allows changing the talent''s facial expression.' hair: type: boolean description: '`true` allows changing the talent''s hair.' pose: type: boolean description: '`true` allows changing the talent''s pose.' wardrobe: type: boolean description: '`true` allows changing what the talent wears.' objects: type: boolean description: '`true` allows adding or changing objects in the scene.' skin_retouch: type: boolean description: '`true` allows retouching the talent''s skin.' endorsement: type: boolean description: '`true` allows outputs that imply the talent endorses something.' prohibited_changes: type: array items: $ref: '#/components/schemas/AdjustmentKind' description: Adjustments that are never allowed. From `terms.prohibitedChanges`. required_attributes: type: array items: $ref: '#/components/schemas/ProtectedAttribute' description: > What every output must keep, checked on the output bytes. Always includes `identity.samePerson`. From `terms.requiredAttributes`. rules: type: object description: >- Rules the talent wrote, as written. From `terms.neverExtras`, `terms.alwaysExtras` and `terms.creationBrief`. properties: never: type: array items: type: string maxLength: 160 description: > What outputs must never show or say, as the talent wrote it, up to 160 characters each. From `terms.neverExtras`. always: type: array items: type: string maxLength: 160 description: > What every output must show or keep, as the talent wrote it, up to 160 characters each. From `terms.alwaysExtras`. brief: type: - string - 'null' maxLength: 160 description: | The talent's brief for outputs, as written. `null` if none. From `terms.creationBrief`. external_creation: type: string enum: - images.v1 description: > The exact signed `terms.externalCreation` grant, when present. `images.v1` is prospective permission for still images made in the licensee's tools using inputs it lawfully holds, subject to request and output checks and mandatory talent release. It grants no export of private references, their identifiers or source bytes. Absence grants nothing; this value is never inferred from `make`, a creation profile or `offPlatformProduction`. This is reader support only: issuance cannot add this term yet, and live checks, output submission and receipts remain unavailable. release_policy: type: string enum: - after_checks - per_output_review description: > `after_checks`: an output that passes its checks is allowed. `per_output_review`: a person releases each output. From `terms.releasePolicy` (`dualCheckBrandRelease`, `perOutputTalentReview`). escalation_window: $ref: '#/components/schemas/Duration' description: > How long an escalation under the license waits for a decision, when shorter than the default 7 days. final_deliverables: type: - integer - 'null' minimum: 1 description: Outputs that may be delivered under the license in total. monthly_limits: type: - object - 'null' description: > Caps on use per month. Past one, checks deny with `monthly_limit_reached`. `null` when the license sets none. properties: outputs: type: integer description: Outputs per month. seconds: type: integer description: Seconds of generated audio or video per month. characters: type: integer description: Characters of generated text or speech per month. asks: type: integer description: >- Knowledge questions per month. From `terms.knowledgeGrant.asksPerMonth`. sessions: type: object description: Whether live sessions may run, and how they are sampled. properties: permitted: type: boolean description: > Whether live sessions may run under the license. When `false`, or when `release_policy` is `per_output_review`, a session is denied with `session_not_permitted`. sampling: $ref: '#/components/schemas/Sampling' description: > How each session must be sampled: the longest audio window, transcripts, and the frame interval for video. material_access: type: array description: >- Facets whose reference material the licensee may download and send to a model. items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ knowledge: type: - object - 'null' description: From `terms.knowledgeGrant`. properties: volume_title: type: string description: The title of the Volume a model may draw on. answers: type: string enum: - summarised - quoted description: > `summarised`: answers paraphrase the Volume. `quoted`: answers may quote it. about: type: array items: type: string description: Topics a model may answer from the Volume. never: type: array items: type: string description: Topics a model must never answer. platforms: type: object description: Which platforms may run checks under this license. properties: mode: type: string enum: - any_connected - listed description: > `any_connected`: any platform the licensee connects. `listed`: only the accounts in `accounts`. accounts: type: array items: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The platforms that may run checks when `mode` is `listed`. Empty for `any_connected`. sublicense: type: string enum: - none - end_users_personal description: >- `end_users_personal`: a platform's end users may make personal, non-commercial outputs under the platform's license. training: type: string enum: - prohibited - permitted default: prohibited description: > Whether covered material and outputs may train a model. `prohibited` puts a `no_training` obligation on each use. Recorded, not enforced. disclosure: type: string enum: - nothing - licensed - brand - scope description: >- The label outputs carry. `licensed` says the likeness is licensed; `brand` adds who licensed it; `scope` adds the use. attribution: type: - string - 'null' description: > A credit line each output must show, delivered as an `attribution` obligation. `null` when the license requires none. Recorded, not enforced. post_revocation: type: object description: What happens to released outputs if the license is revoked. properties: policy: type: string enum: - retain - cease_distribution - withdraw description: > `retain`: released outputs stay usable within their scope and window. `cease_distribution`: no new placements after the revocation. `withdraw`: take them down within `withdraw_within`; only for revocation for cause. withdraw_within: $ref: '#/components/schemas/Duration' description: > For `withdraw`, how long platforms have to take released outputs down after a revocation for cause. exclusivity: type: - object - 'null' description: Recorded, not enforced. properties: exclusive: type: boolean description: > Whether the talent agreed to exclusivity, within `category` when one is named. From `terms.isExclusive`. category: type: - string - 'null' enum: - beauty_and_skincare - fashion - spirits - autos - finance - technology - wellness_and_pharma - gaming - travel - null description: > The product category the exclusivity covers. `null` when it names no category or the license is not exclusive. conflicts: type: array description: >- Brands the talent is not to be associated with during the license. Recorded, not enforced. items: type: object properties: name: type: string description: The brand's name. category: type: - string - 'null' description: >- The brand's product category, such as `spirits`. `null` if not given. compensation: $ref: '#/components/schemas/Compensation' description: >- What the licensee owes the talent. Recorded: statements are computed from it. 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 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. CheckStatus: type: string description: > `checking`: live evaluation has not finished; there is no decision yet. `allowed`, `denied`: decided. `escalated`: waiting for a person; it ends `allowed`, or `denied` with `review_declined` or, after `escalation.expires_at`, `hold_expired`. `consumed`: every allowed generation was used. `expired`: an allowed check's authorization expired unused. `cancelled`: you cancelled it. enum: - checking - allowed - denied - escalated - consumed - expired - cancelled Decision: type: string description: > `allow`: proceed and meet the obligations. `deny`: do not proceed. `escalate`: wait; a person with authority will decide, and an unanswered escalation becomes `deny`. enum: - allow - deny - escalate CheckTalent: type: object required: - talent - name - matched_by - confidence - decision properties: talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent's ID. name: type: string description: The talent's name, to show your user. matched_by: type: string enum: - explicit - name - alias - indirect - reference_image - voice_sample description: > How the request invokes the talent: `explicit` from `talent`, `name` or `alias` in text, `indirect` for a reference such as a role, or `reference_image` or `voice_sample` from media. confidence: type: string enum: - exact - high - medium - low description: > How certain the match is. Every talent at `medium` or higher is treated as invoked. decision: description: > This talent's decision. The check's `decision` is the most restrictive across `talent`. Null while the check is `checking`. oneOf: - $ref: '#/components/schemas/Decision' - type: 'null' facets: type: array items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: The talent's facets the use covers. license: type: - string - 'null' pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: >- The license that decided this talent's use. Null when no license applies. license_revision: type: - string - 'null' pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: >- The revision of `license` that applied. Null when no license applies. terms_digest: description: The `terms_digest` of that revision. Null when no license applies. oneOf: - $ref: '#/components/schemas/Digest' - type: 'null' escalation: type: - string - 'null' pattern: ^esc_[0-9a-hjkmnp-tv-z]{26}$ description: >- This talent's escalation, when their side must decide. Each escalated talent has their own. Use: type: object required: - modality - kind - purpose - commercial properties: modality: $ref: '#/components/schemas/Modality' description: What will be generated. kind: $ref: '#/components/schemas/UseKind' description: How the talent appears in the output. purpose: $ref: '#/components/schemas/Purpose' description: What the output is for. commercial: type: boolean description: >- Whether anyone earns money from the output, including through advertising. channels: type: array items: $ref: '#/components/schemas/Channel' maxItems: 20 description: Required when `commercial` is true. territories: type: array items: $ref: '#/components/schemas/Territory' maxItems: 50 description: Required when `commercial` is true. Reason: type: object required: - code - stage - sentence properties: code: $ref: '#/components/schemas/ReasonCode' description: A stable reason code. Branch on it. stage: type: string enum: - check - generation - session description: 'Where it was decided: `check`, `generation` or `session`.' talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the reason concerns. term: $ref: '#/components/schemas/Address' description: >- The license term or standing rule the reason rests on, as an address. sentence: type: string description: >- The reason in the license's own words. Show it to your user as written. 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. Authorization: type: object description: > Proof that a check allowed a use. A generation tool or provider verifies `token` offline against the JWKS before it generates. For the initial live image submission, send the allowed `check` ID; the server reads its stored token. GenerationCreate has no separate authorization-token field. required: - token - max_generations - generations_used - expires_at properties: token: type: string description: A JWS with `typ` `tlp-auth+jwt`. max_generations: type: integer minimum: 1 description: | How many generations it covers. A generation past it fails with `409 authorization_consumed`. generations_used: type: integer minimum: 0 description: How many generations have been submitted under it. expires_at: type: string format: date-time description: > When it expires, at most 15 minutes after it was issued. A generation after it fails with `409 check_expired`. Escalation: type: object required: - id - reason - reviewer - status - expires_at properties: id: type: string pattern: ^esc_[0-9a-hjkmnp-tv-z]{26}$ description: The escalation's ID, `esc_` followed by 26 characters. reason: type: string enum: - judgment - unverifiable - evaluation_unavailable - release_review description: > `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. reviewer: type: string enum: - talent - representative - reflections description: > `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. status: type: string enum: - open - allowed - denied - expired - cancelled description: > `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. expires_at: type: string format: date-time description: > When an unanswered escalation becomes `deny`: 7 days after it opens, or the license's shorter `escalation_window`. resolved_at: type: - string - 'null' format: date-time description: >- When the escalation was decided, expired or cancelled. Null while `open`. note: type: - string - 'null' maxLength: 500 description: The reviewer's note, if they wrote one. Remedy: type: object description: What would change a `deny`. required: - type properties: type: type: string enum: - license_request - license_change - disambiguate - retry_with_hold description: > `license_request`: no license covers this; request one. `license_change`: a license exists but is narrower; request a change. `disambiguate`: name the talent explicitly. `retry_with_hold`: retry with `on_escalate: hold` to let a person review. license: type: string pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: The license to change, for `license_change`. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent to send a license request to. suggested_scope: $ref: '#/components/schemas/LicenseScopeRequest' description: > The scope that would allow the use, ready to send as `requested_scope` on a license request. GenerationStatus: type: string description: > `checking`: not decided yet. `allowed`: deliver. `denied`: never deliver. `held`: waiting for release. `released`: a reviewer released it; deliver. `expired`: never reviewed. `withdrawn`: you withdrew it. enum: - checking - allowed - denied - held - released - expired - withdrawn Sha256Hex: type: string description: A SHA-256 digest of bytes, as 64 lowercase hex characters. pattern: ^[0-9a-f]{64}$ Execution: type: object description: > Which model will run, or ran, the request. Reflections records it as stated by the platform (`assurance: attested`). properties: provider: type: string maxLength: 100 description: The model provider. model: type: string maxLength: 100 description: The model's name at the provider. candidates: type: integer minimum: 1 maximum: 16 description: Outputs this request will produce. job_id: type: string maxLength: 200 description: The provider's ID for the job. Finding: type: object required: - term - result properties: term: $ref: '#/components/schemas/Address' description: The term's address, such as `license:lic_…/terms.neverExtras`. attribute: type: string description: A protected attribute, such as `identity.samePerson`. rule: type: string description: A rule the talent wrote, as written. result: type: string enum: - preserved - violated - unchecked description: >- `unchecked`: the check could not read this rule. Talent-written rules that are unchecked are delivered and recorded; protected attributes never are. detail: type: string description: What the check saw, for a `violated` result. 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 C2paAssertion: type: object description: Add this assertion to the output's C2PA manifest, under `label`. required: - label - data properties: label: type: string const: ai.reflections.license description: Always `ai.reflections.license`. Use it as the assertion's label. data: type: object description: >- The assertion's data, copied unchanged: the receipt JWS and its public page. required: - receipt - verify_url properties: receipt: type: string description: The receipt JWS. verify_url: type: string format: uri description: >- The receipt's public page, `https://app.reflections.ai/r/{receipt_id}`. Duration: type: string description: An ISO 8601 duration, such as `PT60S` or `P30D`. example: P30D Sampling: type: object properties: audio_window_max: $ref: '#/components/schemas/Duration' description: > Submit an `audio` sample for every window of generated speech, each no longer than this, such as `PT15S`. transcript: type: string enum: - every_turn - none description: > `every_turn`: submit a `transcript` sample with the words of each turn. `none`: no transcript samples. frame_interval: $ref: '#/components/schemas/Duration' description: For video, submit one `frame` sample per interval. ReasonCode: type: string description: >- Why a use was denied or escalated, or a session terminated. See the reason code catalog. enum: - no_license - license_pending_acceptance - license_revoked - license_suspended - window_not_started - window_ended - terms_unreadable - account_not_licensee - material_unavailable - adjustment_not_licensed - facet_not_licensed - kind_not_licensed - modality_not_licensed - purpose_not_licensed - channel_not_licensed - territory_not_licensed - commercial_use_not_licensed - platform_not_licensed - delivery_limit_reached - monthly_limit_reached - talent_prohibits - prohibited_appearance_change - prohibited_endorsement - prohibited_custom_term - identity_not_preserved - prohibited_speech - prohibited_motion - narration_mismatch - voice_rule - unsupported_rule - attribute_unverifiable - output_unverifiable - ambiguous_talent - review_required - unverifiable_request - evaluation_unavailable - authority_changed - provenance_failed - hold_expired - review_declined - review_expired - session_not_permitted - renewal_missed - sample_missed RevocationStatus: type: string description: > `pending_acknowledgement`: some required action is not yet acknowledged. `acknowledged`: every required action is. `overdue`: a deadline passed first, `acknowledge_by` or `post_revocation.withdraw_by`. enum: - pending_acknowledgement - acknowledged - overdue RevocationAction: type: string description: > `stop_generation`: issue nothing new under the targets. `purge_cached_decisions`: drop cached checks and authorizations. `delete_provider_copies`: delete copies held at model providers, such as voices. `cease_distribution`: place released outputs nowhere new. `withdraw_outputs`: take released outputs down. enum: - stop_generation - purge_cached_decisions - delete_provider_copies - cease_distribution - withdraw_outputs 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 FacetStatus: type: string description: >- `preparing`: not usable yet. `ready`: licensable. `withdrawn`: the talent withdrew it; licenses that cover it deny. enum: - preparing - ready - withdrawn 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 ProviderBinding: type: object description: > Where a facet lives at a model provider, such as a voice's ID at a voice provider. Shown only to that provider and to licensees whose license grants material access. required: - provider - kind - external_id - status properties: provider: type: string description: The model provider that holds the copy. kind: type: string enum: - voice - adapter - persona description: >- What the provider holds: a `voice`, a model `adapter` or a `persona`. external_id: type: string description: > The copy's ID at the provider. Call the provider with it, and name it when you report the copy deleted. status: type: string enum: - active - deleted description: >- `deleted` once the copy is gone from the provider. Stop using a deleted copy. Posture: type: object description: > The talent's standing, public answers, before any license. The most specific rule wins; `prohibited` wins a tie. A license can widen `license_required`, never `prohibited`. required: - default - rules - accepts_requests properties: default: $ref: '#/components/schemas/Declaration' description: The declaration that applies when no rule matches. rules: type: array items: $ref: '#/components/schemas/PostureRule' description: > Declarations for particular uses. The most specific matching rule wins, and `prohibited` wins a tie. accepts_requests: type: boolean description: Whether the talent accepts license requests through the API. Representation: type: object description: An account with a mandate to act for the talent. required: - account - name - role - powers properties: account: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The representative's account ID. name: type: string description: The representative's name. role: type: string enum: - agency - manager - estate - union - legal description: What the representative is to the talent. powers: type: array items: type: string enum: - issue_licenses - review_outputs - revoke - receive_statements description: > What the mandate allows. `issue_licenses`: answer requests, and draft and sign licenses. `review_outputs`: decide escalations and release held outputs. `revoke`: revoke or suspend licenses. `receive_statements`: read, confirm and dispute statements. FacetSummary: type: object required: - id - type - label - status properties: id: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: Unique identifier of the facet, prefixed `fct_`. type: $ref: '#/components/schemas/FacetType' description: The part of the talent's identity the facet covers. label: type: string description: The talent's name for the facet, such as "Speaking voice". status: $ref: '#/components/schemas/FacetStatus' description: Whether the facet can be licensed. StatementStatus: type: string description: >- `open`: the month is still running. `issued`: final for the month. `paid`: the talent's side confirmed payment. `disputed`: the talent's side disputed it. enum: - open - issued - paid - disputed UsageUnits: type: string enum: - outputs - seconds - characters - placements - impressions 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. LicenseDraftStatus: type: string description: > `open`: waiting for a signature at `signing_url`. `signed`: signed; `license` and `license_revision` name the result. `declined`: the signer declined it. `discarded`: you discarded it, or the mandate ended. `expired`: not signed by `expires_at`. enum: - open - signed - declined - discarded - expired Input: type: object description: > One part of the request a model receives, in order. Send text inline; send media as a file ID, or as `sha256` with a `url` Reflections can fetch. required: - role properties: role: type: string enum: - prompt - system - negative_prompt - rewritten_prompt - script - reference - voice_sample - mask - context description: > `prompt`: the user's words. `system`: instructions you add. `rewritten_prompt`: your expansion of the prompt, if the model receives that instead. `script`: words to be spoken. `reference`, `voice_sample`, `mask`: media the model receives. `context`: conversation history the model receives. text: type: string maxLength: 32000 description: >- The text, for every role except `reference`, `voice_sample` and `mask`. file: type: string pattern: ^file_[0-9a-hjkmnp-tv-z]{26}$ description: > A file ID from `POST /v1/files`, for a `reference`, `voice_sample` or `mask` input. url: type: string format: uri description: > A URL Reflections can fetch the media from. Send `sha256` and `media_type` with it. sha256: $ref: '#/components/schemas/Sha256Hex' description: > SHA-256 of the bytes, in hex: of the media at `url`, or of a text input's UTF-8 bytes when `prompt_handling.mode` is `withheld`. media_type: type: string example: image/png description: > The MIME type of the media at `url`, or `text/plain` for a withheld text input. 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 ProtectedAttribute: type: string description: >- Something every output must keep. `identity.samePerson` is always required. enum: - identity.samePerson - composition.reframe - composition.background - appearance.lighting - context.textOverlay - appearance.bodyAndAge - appearance.expression - appearance.hair - appearance.pose - appearance.wardrobe - context.objects - appearance.skinRetouch - context.endorsement 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 Declaration: type: string description: > A talent's public answer for a kind of use. `allowed`: no license needed; follow the obligations. `license_required`: request a license. `prohibited`: never, and no license can be requested. enum: - allowed - license_required - prohibited PostureRule: type: object description: One public declaration. Omitted fields match every value. required: - declaration properties: modality: $ref: '#/components/schemas/Modality' description: The modality the rule matches. kind: $ref: '#/components/schemas/UseKind' description: The use kind the rule matches. purpose: $ref: '#/components/schemas/Purpose' description: The purpose the rule matches. commercial: type: boolean description: Whether the rule matches commercial or non-commercial uses. declaration: $ref: '#/components/schemas/Declaration' description: The talent's answer for the uses the rule matches. obligations: type: array description: What a use declared `allowed` must do. items: $ref: '#/components/schemas/Obligation' 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 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.