BASETEN_API_KEY. Resources nest as: sessions own runs and samplers; runs own checkpoints; deployments are produced from checkpoints.
Each route’s request body, query parameters, response shape, and an interactive playground live on its own page in this section. This overview covers the resource model, the authentication scope each route requires, and the legacy paths that still resolve.
Both the HTTP API and the Python SDK refer to a trainer server as a run_id. Legacy /v1/trainer_sessions/* routes still work for backwards compatibility, but the /v1/loops/* paths are canonical.
Authentication scopes
Auth scope varies per route. Pass your key asAuthorization: Bearer $BASETEN_API_KEY; the playground on each route page prefills this header.
| Method | Route | Auth scope |
|---|---|---|
POST | /v1/loops/sessions | manage_org_training_projects |
GET | /v1/loops/sessions/{session_id} | manage_org_training_projects |
POST | /v1/loops/runs | manage_org_training_projects |
GET | /v1/loops/runs | manage_own_user_or_service_account |
GET | /v1/loops/runs/{run_id} | manage_org_training_projects |
POST | /v1/loops/samplers | manage_org_training_projects |
GET | /v1/loops/samplers | manage_own_user_or_service_account |
GET | /v1/loops/samplers/{sampler_id} | manage_org_training_projects |
GET | /v1/loops/checkpoints | manage_own_user_or_service_account |
POST | /v1/loops/checkpoints/validate | manage_own_user_or_service_account |
GET | /v1/loops/checkpoints/{checkpoint_id}/files | manage_org_training_projects |
GET | /v1/loops/deployments | manage_org_training_projects |
GET | /v1/loops/deployments/{deployment_id} | manage_org_training_projects |
POST | /v1/loops/deployments/{deployment_id}/deactivate | manage_org_training_projects |
POST | /v1/loops/deployments/{deployment_id}/metrics | manage_org_training_projects |
GET | /v1/loops/capabilities | manage_own_user_or_service_account |
Legacy routes
The previous/v1/trainer_sessions/* and /v1/trainers/* paths still work. Use the /v1/loops/* paths for new integrations.
| Method | Path |
|---|---|
POST | /v1/trainers/search |
POST | /v1/trainers/checkpoints/search |
POST | /v1/trainer_sessions |
POST | /v1/trainer_sessions/{session_id}/trainers |
POST | /v1/trainer_sessions/{session_id}/samplers |
GET | /v1/trainer_sessions/{session_id}/trainers/{trainer_id}/checkpoints |
GET | /v1/trainer_sessions/{session_id}/trainers/{trainer_id}/checkpoints/{checkpoint_id}/files |