> ## 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 revocations > **Test mode available. Live mode unavailable.** The sandbox feed is always empty. Creating and applying revocations is not implemented. The revocation feed. Pass `after` with the last revocation ID you processed to read everything since, oldest first. Platforms that cache decisions must read this feed at least every 60 seconds; webhooks are the fast path, this is the source of truth. A representative sees the revocations of every talent it represents, with each platform's acknowledgements. Restricted keys need `revocations:read` or `revocations:write`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /revocations 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: /revocations: get: tags: - Revocations summary: List revocations description: > **Test mode available. Live mode unavailable.** The sandbox feed is always empty. Creating and applying revocations is not implemented. The revocation feed. Pass `after` with the last revocation ID you processed to read everything since, oldest first. Platforms that cache decisions must read this feed at least every 60 seconds; webhooks are the fast path, this is the source of truth. A representative sees the revocations of every talent it represents, with each platform's acknowledgements. Restricted keys need `revocations:read` or `revocations:write`. operationId: listRevocations parameters: - $ref: '#/components/parameters/ReflectionsVersion' - $ref: '#/components/parameters/ReflectionsAccount' - name: talent in: query description: Only revocations whose `targets.talent` is this talent. schema: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ - name: after in: query description: Return revocations created after this one, oldest first. schema: type: string pattern: ^rvk_[0-9a-hjkmnp-tv-z]{26}$ - name: status in: query description: > Only revocations with this status. `pending_acknowledgement` and `overdue` list the ones that still need acknowledging. schema: $ref: '#/components/schemas/RevocationStatus' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of revocations. 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/RevocationList' examples: feed_after_cursor: summary: The feed after a cursor, oldest first value: object: list data: - id: rvk_6z4ke43tnnk4h14drgv1tt82q1 object: revocation livemode: true scope: license targets: talent: tal_4n6p8r0t2v4x6z8b0d2f4h6j8k licenses: - lic_zfjz8gb26kcd5ynj2tpb55e8bp facets: [] mandate: null status: overdue initiated_by: talent for_cause: true cause: Outputs used outside the licensed territories. note: null effective_at: '2026-10-02T15:20:00Z' post_revocation: policy: withdraw withdraw_by: '2026-10-09T15:20:00Z' required_actions: - stop_generation - purge_cached_decisions - withdraw_outputs provider_copies: [] affected: checks_denied: 0 generations_denied: 1 sessions_terminated: 0 released_outputs: 14 acknowledge_by: '2026-10-03T15:20:00Z' acknowledgements: - account: acct_7p4r6s9t0wxyhk5zba2q8v1m3n actions: - stop_generation - purge_cached_decisions deleted_copies: [] note: >- Generation stopped and caches purged. Takedowns are in progress. acknowledged_at: '2026-10-02T15:34:51Z' created_at: '2026-10-02T15:20:00Z' - id: rvk_s9t0wxyhk5zba2q8v1m3n7p4r6 object: revocation livemode: true scope: license targets: talent: tal_9t0wxyhk5zba2q8v1m3n7p4r6s licenses: - lic_ba2q8v1m3n7p4r6s9t0wxyhk5z facets: - fct_v1m3n7p4r6s9t0wxyhk5zba2q8 mandate: null status: pending_acknowledgement initiated_by: talent for_cause: false cause: null note: null effective_at: '2026-10-17T18:03:40Z' post_revocation: policy: retain withdraw_by: null required_actions: - stop_generation - purge_cached_decisions - delete_provider_copies provider_copies: - facet: fct_v1m3n7p4r6s9t0wxyhk5zba2q8 provider: example-voice-provider external_id: vx_4f9a2c affected: checks_denied: 3 generations_denied: 0 sessions_terminated: 1 released_outputs: 418 acknowledge_by: '2026-10-18T18:03:40Z' acknowledgements: [] created_at: '2026-10-17T18:03:40Z' 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: - revocations:read - SecretKey: - revocations:write 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/revocations?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/revocations?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/revocations?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/revocations?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' ReflectionsAccount: name: Reflections-Account in: header required: false description: > Act for a connected licensee. The value is the licensee's account ID. Requires an active connection between that account and yours. schema: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ 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 schemas: 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 RevocationList: allOf: - $ref: '#/components/schemas/ListBase' - type: object properties: data: type: array items: $ref: '#/components/schemas/Revocation' description: >- Revocations, 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. 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. 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. 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 ErrorCode: type: string description: A stable error code. See the error code catalog. enum: - invalid_request - parameter_missing - parameter_invalid - unsupported_modality - unsupported_media_type - media_unreadable - version_unsupported - authorization_code_invalid - authentication_required - invalid_api_key - token_invalid - insufficient_scope - account_not_connected - mandate_required - livemode_mismatch - live_not_activated - platform_not_permitted - resource_not_found - idempotency_key_in_use - generation_already_submitted - authorization_consumed - check_not_allowed - check_expired - escalation_closed - license_draft_closed - invalid_state_transition - session_not_active - payload_too_large - idempotency_key_reused - artifact_digest_mismatch - rate_limited - internal_error - service_unavailable - evaluation_timeout headers: RequestId: description: Identifies this request. Include it when you contact support. schema: type: string example: req_8f2k4m6p8r0t2v4x6z8b0d2f4h RateLimit: description: >- Remaining quota and seconds until it resets, as IETF RateLimit header fields. schema: type: string example: '"checks";r=184;t=1' RateLimitPolicy: description: The policy the RateLimit field reports against. schema: type: string example: '"checks";q=200;w=1' RetryAfter: description: Seconds to wait before retrying. schema: type: integer responses: BadRequest: description: The request was malformed or a parameter was invalid. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/parameter_invalid title: A parameter is invalid status: 400 code: parameter_invalid param: use.territories[1] detail: '"UK" is not an ISO 3166-1 alpha-2 code. Use "GB".' request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Unauthorized: description: The key is missing, unknown or revoked. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/invalid_api_key title: The API key is not valid status: 401 code: invalid_api_key request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Forbidden: description: >- The key may not do this, the licensee is not connected, or live mode is not activated for this operation (`live_not_activated`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/account_not_connected title: The licensee has not connected your platform status: 403 code: account_not_connected detail: >- acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account. request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h 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.