concepts

Projects & workloads

Two levels of scope organize everything the gateway records and routes. A project is a product surface; a workload is one stable call site within it. Routing and capture both operate at the workload level — getting this model right is what makes per-call-site optimization possible.

The scoping model

organization
└── project            "concierge"        one product surface
    ├── workload       "main"             default — catches unscoped traffic
    ├── workload       "ad-copy"          one stable call site
    └── workload       "spam-detection"   another call site

Requests declare their scope with two optional headers. Both default sensibly, so unscoped traffic still works and still lands somewhere meaningful:

header	absent →
`x-understudy-project: concierge`	your org's default project (slug `rehearsal`)
`x-understudy-workload: ad-copy`	the project's default workload (`main`)

Projects

A project's slug is its identity — it appears in the header, in capture storage paths, and in dashboard URLs. Slugs are immutable; the display name can be renamed freely without touching live traffic. Slugs are lowercase letters, numbers, and hyphens. Deleting a project is a soft delete: the slug stops resolving on the gateway (and becomes reusable), while already-written captures remain in storage.

Every organization gets a default project named rehearsal at signup, created idempotently — the dashboard, the CLI, and the first proxied request all converge on the same row.

Workloads

A workload is the unit the whole product operates on: capture is toggled per workload, capture sampling is set per workload, and model routes attach to workloads. Use one workload per stable call site — the prompt that scores ad relevance is a different workload from the one that writes ad copy, even if both live in the same service.

field	meaning
`name`	Lowercase alphanumerics, hyphens, underscores; 1–63 chars (it travels in an HTTP header). Renameable — but callers sending the old name stop resolving, so coordinate the change.
`capture_enabled`	Whether this workload's traffic is recorded. Routing a workload to a model turns capture on by default — routed traffic is exactly the traffic worth evaluating.
`capture_sample_rate`	0.0–1.0 fraction of capturable requests actually written. Sampling is deterministic per request id, so a retried request is consistently captured or consistently skipped.
`route_model_id / route_traffic_pct`	The model route, if any — see Routing.
`is_default`	Exactly one per project. The default workload receives traffic that doesn't name a workload, and it can't be deleted.