> ## 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.
# Monitoring
> Log request IDs, watch the numbers that show a broken integration, and alert on revocations, webhook failures and outages.
The Talent API serves the fictional [sandbox](/sandbox) and three
[live account/license reads](/api-reference/introduction#test-and-live-mode). Log request IDs, error
codes, rate-limit headers and client timings for the supported endpoints. The webhook, session,
usage and revocation workflows below are production planning guidance; they are not available
monitoring features of the current sandbox. Start with the [quickstart](/quickstart).
For a future live integration, successful checks alone will not establish health: escalations,
held outputs and revocations also need deadline monitoring.
## Log request IDs
Every response carries a `Request-Id` header, such as `req_8f2k4m6p8r0t2v4x6z8b0d2f4h`. Every
error body carries the same value as `request_id`.
```json theme={null}
{
"type": "https://docs.reflections.ai/errors/rate_limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}
```
Log it with every call, next to the object IDs involved (`chk_…`, `gen_…`, `ses_…`, `rvk_…`) and
your own job ID. When you contact [support](/production/support), the request ID is the fastest way
to find what happened. Log the `code` of every error, not only the HTTP status: a `409` can mean
anything from `idempotency_key_in_use` to `session_not_active`.
Do not log secret keys, webhook secrets or whole tokens, and keep prompt text out of shared logs.
## What to measure
Use the rows that match supported endpoints today. Rows for unserved capabilities are targets
for a future integration; their dashboard views and background processing are not available yet.
| Measure | Why it matters | Source |
| - | - | - |
| Decisions by `decision` and `reasons[].code` | A jump in one reason usually means a pipeline change, such as a new rewrite step adding text | Check responses |
| Escalated checks still open, and the oldest | Users waiting; escalations expire after 7 days | Your job store, or `GET /v1/checks?status=escalated` |
| Held generations, and the oldest | Held outputs expire after 7 days | `GET /v1/generations?status=held` |
| Generations by `status`, and time to decision | Asynchronous checks running late, or outputs delivered without one | Generation responses and events |
| Revocations by `status`, and which required actions are unacknowledged | An action other than `withdraw_outputs` near `acknowledge_by`, or `withdraw_outputs` near `post_revocation.withdraw_by`, is about to go overdue | `GET /v1/revocations?status=pending_acknowledgement` |
| Webhook delivery failures | Planned policy: disable a continuously failing endpoint after 5 days | Planned delivery records, and your endpoint's own logs |
| Errors by `code` | `artifact_digest_mismatch`, `generation_already_submitted` and `idempotency_key_reused` point at bugs; `503` and timeouts at availability | Error bodies |
| Rate limit headroom | Running near the limit turns traffic peaks into `429`s | `RateLimit` and `RateLimit-Policy` headers |
| Latency per endpoint | Record your measured baseline; the proposed p95 targets of 150 to 500 ms for checks and 2 s for image generations are not verified service guarantees | Your client timings |
| Session terminations by `termination.reason` | Denied samples or revocations cutting calls | Session events |
| Rejected usage records by `rejection.code` | Under-reporting shows on statements | Usage record responses |
## Alerts
These are proposed operational alerts for the full API. The sandbox does not deliver the named
webhook events or run the background deadline workflows.
| Condition | Severity | What to do |
| - | - | - |
| A required action other than `withdraw_outputs` is unacknowledged an hour after `effective_at` | Page | Find the step that stalled and finish it. The deadline is `acknowledge_by`, 24 hours after `effective_at`. |
| `withdraw_outputs` is unacknowledged halfway from `effective_at` to `post_revocation.withdraw_by` | Page | Finish taking released outputs down, then acknowledge `withdraw_outputs`. |
| [`revocation.overdue`](/api-reference/webhooks/revocation-overdue) | Page | Acknowledge the late actions now: those due by `acknowledge_by` if it passed, or `withdraw_outputs` if `withdraw_by` passed. It is shown as overdue on the talent's record. |
| [`license.suspended`](/api-reference/webhooks/license-suspended) | Ticket | Confirm that cached decisions under the license were dropped. A suspension is not a revocation: there is nothing to acknowledge. |
| [`webhook_endpoint.disabled`](/api-reference/webhooks/webhook-endpoint-disabled) | Page | Fix the endpoint, re-enable it, and replay missed events. |
| Webhook deliveries failing for more than an hour | Page | Your revocation feed polling is now the only path. Check it is running. |
| `503 service_unavailable` above your normal rate | Page | Check [status.reflections.ai](https://status.reflections.ai). Named-talent generation is failing closed. |
| Revocation feed not read for more than 2 minutes | Page | Your cached decisions are no longer safe to serve. |
| Escalations older than 3 days | Ticket | Tell the affected users, or cancel what they no longer need. |
| Rejected usage records | Ticket | Correct them with `correction_of`. |
## Revocations
Revocations carry hard deadlines on your side: `acknowledge_by` for every required action except
`withdraw_outputs`, and `post_revocation.withdraw_by` for `withdraw_outputs`. Watch them three ways:
1. The [`revocation.created`](/api-reference/webhooks/revocation-created) handler records each
revocation and when it was received.
2. Your feed reader records each `GET /v1/revocations?after=…` call and the cursor it reached, and
alerts when it stops running.
3. A scheduled job lists `status=pending_acknowledgement` and `status=overdue`, alerts at once on
any overdue revocation, and compares each pending revocation's `acknowledgements` with its
`required_actions`. It alerts on each deadline separately: actions
other than `withdraw_outputs` still unacknowledged long before `acknowledge_by`, and
`withdraw_outputs` still unacknowledged long before `post_revocation.withdraw_by`. A revocation
that requires `withdraw_outputs` stays `pending_acknowledgement` after your first call, so that
status alone is not a fault.
## Webhook health
Hosted webhook delivery is not available in the current sandbox. The proposed production policy
is to retry a failed delivery with exponential backoff for 72 hours: after about 5
seconds, 1 minute, 5 minutes, 30 minutes, 2 hours and 5 hours, then every 10 hours. An endpoint that
fails every delivery for 5 days would be disabled, and `webhook_endpoint.disabled` would go to your other
endpoints and your account email.
The planned recovery flow after an outage is to read missed events with
[`GET /v1/events`](/api-reference/events/list-events) and `after` set to the last event you
processed, or resend single events with
[`POST /v1/events/{event_id}/resend`](/api-reference/events/resend-an-event). Events are kept for 30
days under the proposed policy. These event endpoints are not served by the current sandbox.
## Status page
[status.reflections.ai](https://status.reflections.ai) provides the published service status.
Link it from your runbook and check which components it covers. It does not replace testing the
Talent API journey your integration uses. The 99.95% monthly availability figure and latency
figures in the API design are proposed targets, not a verified SLA for the sandbox. Incident
subscriptions and response commitments must be confirmed before relying on them.
Exercise alerts for supported sandbox errors now. Rehearse revocation deadlines and webhook
delivery failures when those capabilities become available; the current sandbox cannot perform
those rehearsals.
## Related
The problem-details format and every error code.
Limits, headers and raising them.
The feed, purges and acknowledgements.
How to reach Reflections and what to send.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.