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 |
|---|---|
| keys | any JSON property name, including uppercase, underscores, and dots |
| values | strings |
| header size | at most 16 KiB (16,384 UTF-8 bytes) for the complete JSON header value |
-H 'x-understudy-tags: {"env":"prod","tenant":"acme","release":"2026.24"}'Tags are optional. If the header is malformed or violates these constraints, the entire tag set is ignored and the request proceeds without tags. There are no separate entry-count or per-value limits. Tags stay within Understudy and are never forwarded to providers.