> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Loops API reference

> HTTP routes for Loops sessions, runs, samplers, checkpoints, and deployments.

Every Loops API call is authenticated with `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 as `Authorization: Bearer $BASETEN_API_KEY`; the playground on each route page prefills this header.

| Method | Route                                                                                                          | Auth scope                           |
| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `POST` | [`/v1/loops/sessions`](/reference/loops-api/sessions/create-a-session)                                         | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/sessions/{session_id}`](/reference/loops-api/sessions/get-a-session)                               | `manage_org_training_projects`       |
| `POST` | [`/v1/loops/runs`](/reference/loops-api/runs/create-a-run)                                                     | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/runs`](/reference/loops-api/runs/list-runs)                                                        | `manage_own_user_or_service_account` |
| `GET`  | [`/v1/loops/runs/{run_id}`](/reference/loops-api/runs/get-a-run)                                               | `manage_org_training_projects`       |
| `POST` | [`/v1/loops/samplers`](/reference/loops-api/samplers/create-a-sampler)                                         | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/samplers`](/reference/loops-api/samplers/list-samplers)                                            | `manage_own_user_or_service_account` |
| `GET`  | [`/v1/loops/samplers/{sampler_id}`](/reference/loops-api/samplers/get-a-sampler)                               | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/checkpoints`](/reference/loops-api/checkpoints/list-checkpoints)                                   | `manage_own_user_or_service_account` |
| `POST` | [`/v1/loops/checkpoints/validate`](/reference/loops-api/checkpoints/validate-a-checkpoint)                     | `manage_own_user_or_service_account` |
| `GET`  | [`/v1/loops/checkpoints/{checkpoint_id}/files`](/reference/loops-api/checkpoints/get-checkpoint-files)         | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/deployments`](/reference/loops-api/deployments/list-deployments)                                   | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/deployments/{deployment_id}`](/reference/loops-api/deployments/get-a-deployment)                   | `manage_org_training_projects`       |
| `POST` | [`/v1/loops/deployments/{deployment_id}/deactivate`](/reference/loops-api/deployments/deactivate-a-deployment) | `manage_org_training_projects`       |
| `POST` | [`/v1/loops/deployments/{deployment_id}/metrics`](/reference/loops-api/deployments/get-deployment-metrics)     | `manage_org_training_projects`       |
| `GET`  | [`/v1/loops/capabilities`](/reference/loops-api/server/get-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` |