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

# Atlas

> The identity graph behind talent resolution, and how talent confirm what it holds.

<Note>
  Planned production capability. The current sandbox matches a fixed fictional catalog; it does
  not provide the production identity graph or recognition capabilities described below.
  Start with the [runnable quickstart](/quickstart) and [sandbox support matrix](/sandbox).
</Note>

**Atlas** is the identity graph Reflections uses to find which talent a request invokes. It holds
each talent's names, aliases, transliterations, credits and roles, representation and facets.
Atlas is not an endpoint. You meet it through [resolution](/concepts/resolution), the name index
and the talent object.

## What Atlas holds

| Entry | Example | Used for |
| - | - | - |
| Name | Maya Okafor | Matching the name in text |
| Aliases | A stage name, a former name | Matching other names the talent uses |
| Transliterations | The name in other scripts | Matching the name in any language |
| Credits and roles | Host of the Ridge Runners podcast | Matching indirect references |
| Representation | Her agency, with its powers | Routing reviews and statements |
| Facets | Studio likeness, Speaking voice | Deciding what a license covers |

## Talent confirm every entry

An entry is used for matching only after the talent confirms it in the Talent Portal. A credit that
a fan site lists, or that a model associates with the talent, is not in Atlas until the talent
confirms it. This keeps indirect matches tied to facts the talent stands behind, and it means a
wrong credit is fixed at its source.

When a talent's names, aliases, posture or protection change, you receive `talent.updated`.
Refresh your name index when it arrives.

## Where Atlas appears in the API

| In the API | From Atlas |
| - | - |
| `talent.name`, `talent.aliases` | Confirmed names and aliases |
| [Name index](/api-reference/talent/download-the-name-index) `entries[].names` | Name, aliases and transliterations, normalized with `nfkc_casefold` |
| Name index `entries[].common` | The name is common enough that a match alone is weak evidence |
| `talent.representation` | Representatives and their powers |
| `talent.facets` | Each facet and its status |
| `matched_by: "indirect"` on a resolution or check | A match through a confirmed credit or role |

Credits and roles are not returned as fields. They show up as indirect matches, with the `span` of
text that matched.

## Indirect references

A prompt can invoke a talent without naming them: "the host of Ridge Runners", "the runner who
won the 2025 desert ultra". Resolution looks these up against confirmed credits and roles. An
indirect match usually has `confidence: "medium"`, and checks treat every candidate at `medium` or
higher as invoked.

```mermaid theme={null}
flowchart LR
    T[Talent confirms entries] --> A[Atlas]
    A --> I[Name index]
    A --> R[Resolution]
    I -->|local match| C[Check]
    R --> C
```

An indirect reference is found only when the credit behind it is in Atlas. A request that describes
a person without naming or crediting them ("a tall trail runner with a broadcaster's voice") is not
resolved, and outputs are checked only for the talent their check covered. See
[Generation checks](/concepts/generation-checks#which-talent-are-checked).

The name index holds names only. A local match against it tells you to send a check; no local
match does not clear a prompt, because indirect references and reference media need the server.

## Example: the host of Ridge Runners

Maya Okafor confirmed her credit as host of the Ridge Runners podcast. A voice app resolves a
prompt that does not use her name:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.reflections.ai/v1/resolutions \
    -H "Authorization: Bearer rk_test_…" \
    -H "Reflections-Version: 2026-10-15" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "inputs": [{ "role": "prompt", "text": "The host of Ridge Runners reading today'\''s trail report" }],
      "modality": "speech"
    }'
  ```

  ```typescript TypeScript theme={null}
  const resolution = await fetch("https://app.reflections.ai/v1/resolutions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
      "Reflections-Version": "2026-10-15",
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inputs: [{ role: "prompt", text: "The host of Ridge Runners reading today's trail report" }],
      modality: "speech",
    }),
  }).then((r) => r.json());
  ```

  ```python Python theme={null}
  import os, uuid, requests

  resolution = requests.post(
      "https://app.reflections.ai/v1/resolutions",
      headers={
          "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
          "Reflections-Version": "2026-10-15",
          "Idempotency-Key": str(uuid.uuid4()),
      },
      json={
          "inputs": [{"role": "prompt", "text": "The host of Ridge Runners reading today's trail report"}],
          "modality": "speech",
      },
  ).json()
  ```
</CodeGroup>

```json theme={null}
{
  "id": "res_8k2m4p6r8t0v2x4z6b8d0f2h4j",
  "object": "resolution",
  "status": "matched",
  "candidates": [
    {
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "name": "Maya Okafor",
      "matched_by": "indirect",
      "confidence": "medium",
      "span": { "input": 0, "start": 0, "end": 25, "text": "The host of Ridge Runners" },
      "licensed": true,
      "declaration": "license_required"
    }
  ],
  "use_kind": "impersonation"
}
```

A check on the same prompt treats Maya Okafor as invoked and decides against the license that
covers the use, exactly as if the prompt had named her.

## Related

<Columns cols={2}>
  <Card title="Resolution" icon="magnifying-glass" href="/concepts/resolution">
    Matching, confidence, and why no match is not permission.
  </Card>

  <Card title="Resolving talent" icon="code" href="/build/resolving-talent">
    Explicit IDs, autocomplete and the local name index.
  </Card>

  <Card title="Talent and facets" icon="user" href="/concepts/talent-and-facets">
    The talent object, posture and facets.
  </Card>
</Columns>


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