getting started

Introduction

Understudy is a gateway for your LLM traffic: a drop-in replacement for the Anthropic and OpenAI API endpoints that captures your requests, lets you scope them into projects and workloads, and shifts slices of traffic onto smaller managed models — without changing your application code.

What the gateway does

You point your SDK's base URL at https://api.understudylabs.com and authenticate with an Understudy sk_* key. From that one change you get:

Passthrough. Requests forward to the provider your code already calls — your Anthropic or OpenAI account, your keys, same wire format, same responses.
Capture. Each request/response pair can be recorded as evidence — the raw material for evals and fine-tuning data, scoped to the workload it came from.
Routing. Any workload can route a percentage of its traffic to a model Understudy serves from managed supply, and roll back to passthrough instantly.
Managed models. Catalog models are callable directly by id with only your Understudy key — no provider account needed.

Two surfaces

The data plane is the gateway at api.understudylabs.com — it proxies your model traffic and is what these API docs describe. The control plane is the dashboard at app.understudylabs.com — keys, projects, workloads, capture inspection, and routing controls. Everything the dashboard does is also reachable programmatically through the admin API that backs it.

Where to go next

Getting started

QuickstartFrom an sk_* key to a captured request in five minutes — both connection paths.Your workspaceWhat signup creates for you, and a map of the dashboard's pages.AuthenticationUnderstudy keys: how to send them, where they work, how to manage them.

Tutorials

First captured requestZero to a recorded request/response pair you can read in the dashboard.Replace a model on live trafficThe whole loop: isolate a call site, baseline it, route 5%, compare, ratchet.Build an eval set from capturesUse tags and sampling so the captures you collect become a dataset, not a pile.

Concepts

ArchitectureThe data plane, the control plane, and the five-phase request pipeline.Projects & workloadsThe two-level scoping model that organizes traffic, captures, and routing.Modes: BYO & managedWhose credential pays for the upstream call, and what each mode permits.RoutingPassthrough, model routes, traffic percentages, the catalog arm, and fallback.CaptureWhat the gateway records, how sampling works, and what the envelope contains.

Guides

Route a workloadShift a slice of live traffic onto a managed model, verify, and ratchet up.Scope with projectsKeep environments and product surfaces isolated using scoping headers.Tag requestsAttach your own dimensions to captures with x-understudy-tags.

Gateway API

Proxy endpointsThe OpenAI- and Anthropic-compatible surface at api.understudylabs.com.Request headersEvery x-understudy-* header you can send, with limits.Response headersThe legibility headers that tell you how each request resolved.ErrorsThe error envelope and every error type the gateway returns.

Control plane API

OverviewAuth, conventions, and the path families behind the dashboard and the CLI.API keysList, create, and revoke sk_* keys programmatically.ProjectsCreate, list, rename, and soft-delete projects; ensure the default.Workloads & routingWorkload CRUD, the model catalog, and the route write endpoints.CapturesList capture objects and fetch a single envelope by request id.

Open source

Agent toolsThe MIT-licensed local client: skills for coding agents plus a thin CLI.CLI referenceEvery understudy command in the public CLI, with the first hosted journey.