gateway api
Request headers
Four optional x-understudy-* headers control scope, credentials, and attribution. All of them have sensible absences — a request with none of them still authenticates, resolves to your default project's main workload, and forwards.
Authentication headers
| header | carries |
|---|---|
x-api-key | Your Understudy sk_* key, Anthropic-style (on /v1/messages) |
Authorization: Bearer | Your Understudy sk_* key, OpenAI-style (works on both endpoints) |
Scoping & credential headers
| header | value | absent → |
|---|---|---|
x-understudy-project | a project slug, e.g. concierge | default project (rehearsal) |
x-understudy-workload | a workload name, e.g. ad-copy | the project's default workload (main) |
x-understudy-upstream-key | your Anthropic or OpenAI provider key | managed mode — Understudy's credential pays upstream |
x-understudy-tags | a flat JSON object of strings | no tags on the capture |
Tag constraints
Tags attach your own dimensions to captures — guide here. The value must be a flat JSON object of string values, with:
| constraint | limit |
|---|---|
| entries | at most 16 |
| keys | lowercase alphanumerics and hyphens, 1–64 chars (^[a-z0-9][a-z0-9-]*$) |
| values | strings, at most 256 bytes each |
-H 'x-understudy-tags: {"env":"prod","tenant":"acme","release":"2026.24"}'A malformed tags header fails the request with 400 invalid_request_errornaming the offending key — tags are attribution you'll filter datasets by later, so silent truncation would be worse than an error.