> ## 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.

# Versioning

> The /v1 path, dated versions in Reflections-Version, account pinning, and what counts as a breaking change.

The API has two version numbers. The major version is in the path, `/v1`, and changes only for a new
API. The dated version is in the `Reflections-Version` header and changes when a release would
break an integration. The current dated version is `2026-10-15`.

## Send a version

Send `Reflections-Version` on every request:

```bash theme={null}
curl https://app.reflections.ai/v1/checks/chk_3m7p4r6s9t0wxyhk5zba2q8v1n \
  -H "Authorization: Bearer rk_test_…" \
  -H "Reflections-Version: 2026-10-15"
```

| Case | What happens |
| - | - |
| A supported version | The request and response use that version. |
| No header | Your account's pinned version is used. `GET /v1/account` returns it as `api_version`. |
| An unknown version | `400 version_unsupported`. |

The [discovery document](/api-reference/formats/discovery) lists every supported version in
`api_versions`.

## Pinning

Your account is pinned to the version that was current when it made its first request. The pin is
what requests without the header use. A header on one request changes only that request.

Webhook endpoints are pinned separately. Each endpoint renders events in its own `api_version`, set
when you [create the endpoint](/api-reference/webhook-endpoints/create-a-webhook-endpoint) and
defaulting to your account's version. Every event carries the `api_version` it was rendered in.

## Changes without a new date

These ship to every version, so write code that accepts them:

* New endpoints.
* New optional request fields and query parameters.
* New fields in responses and events.
* New event types. Endpoints subscribed to `["*"]` receive them.
* New values in response enums, such as a reason code. Show `reasons[].sentence` for a reason
  code you do not recognize, and deliver nothing for a generation `status` you do not recognize.
* New response headers.

## Changes that get a new date

* Removing or renaming an endpoint, a field or an enum value.
* Changing a field's type, format or meaning.
* Making an optional request field required, or changing a default.
* A new obligation type.

Each new date ships with a migration guide in the [changelog](/changelog). Every dated version is
supported for at least 24 months.

<Warning>
  A new obligation type always comes with a new dated version, so a pinned integration does not
  receive one it was not built for. If you receive an obligation `type` you do not recognize, treat
  it as unmet: do not generate and do not deliver.
</Warning>

## Upgrade

<Steps>
  <Step title="Read the migration guide">
    The [changelog](/changelog) entry for the new date lists every change and what to do about it.
  </Step>

  <Step title="Test with the header">
    Send the new `Reflections-Version` from a test-mode build and run your integration tests.
    Use the [proposed conformance cases](/production/conformance) as a guide; no hosted runner
    is available.
  </Step>

  <Step title="Move your webhooks">
    Create a new webhook endpoint with the new `api_version`, verify that it receives events, then
    delete the old endpoint. An endpoint's `api_version` cannot be changed after it is created.
  </Step>

  <Step title="Move your pin">
    Change your account's default version in the [dashboard](https://app.reflections.ai/developers).
    Requests that send the header are not affected.
  </Step>
</Steps>

## Protocol versions

The dated API version is separate from the version of the
[Talent License Protocol](/standard/overview). Tokens and receipts carry the protocol version in
`tlp.ver` (`"1.0"`), and the discovery document lists supported protocol versions in
`protocol_versions`. See [Changes to the Standard](/standard/changes).

## Related

<Columns cols={2}>
  <Card title="Changelog" icon="book" href="/changelog">
    Every dated version and what changed.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    How events are rendered and delivered.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.