control plane api
Control plane API
Everything the dashboard and the CLI do goes through this REST surface — keys, projects, workloads, routing writes, capture listings. It shares the gateway's host and error envelope but never touches live model traffic.
Base URL & auth
The control plane is served from the same public host as the gateway. Authenticate with your sk_* key as a bearer token — the same credential the proxy takes, and what the CLI sends after understudy login. (The dashboard authenticates the same routes with its own session tokens; the resources and shapes are identical.)
curl https://api.understudylabs.com/admin/v1/orgs/$ORG_ID/projects \
-H "Authorization: Bearer $UNDERSTUDY_API_KEY"Conventions
| convention | details |
|---|---|
| org-scoped paths | Every route nests under /orgs/:org_id. The org id in the path must match the credential's organization — cross-org references fail with 403 authorization_error. |
| two path families | /admin/v1/* carries keys, projects, the model catalog, and routing writes; /customer/v1/* carries tenant-scoped workload CRUD and capture reads. Same auth, same envelope — the split is internal layering, and both are documented in the resource pages here. |
| errors | The same envelope and types as the gateway — see Errors. Every response carries x-understudy-request-id. |
| pagination | List endpoints take ?limit= and an opaque ?cursor=; responses return the next cursor when more pages exist. Pass it back verbatim. |
| validation | Request bodies are schema-validated; a violation returns 400/422 with a message naming the offending field. |
Resources
| resource | page |
|---|---|
| API keys — mint, list, revoke | /reference/control-plane/keys |
| Projects — create, list, rename, delete, default | /reference/control-plane/projects |
| Workloads, model catalog, routes | /reference/control-plane/workloads-routing |
| Captures — list, fetch one | /reference/control-plane/captures |