Agent Rollouts
All paths below are relative to the base URL https://api.agentdepot.org — for example
GET https://api.agentdepot.org/api/orgs/{org_id}/agents/{agent_id}/rollouts. Authenticate with an
Authorization: Bearer <token> header. See the
REST API reference for details.
GET /api/orgs/{org_id}/agents/{agent_id}/rollouts
Section titled “GET /api/orgs/{org_id}/agents/{agent_id}/rollouts”List Rollouts
List every rollout (deploys and experiments) an agent has ever had, newest first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutListResponse |
| 422 | Validation Error | HTTPValidationError |
POST /api/orgs/{org_id}/agents/{agent_id}/rollouts
Section titled “POST /api/orgs/{org_id}/agents/{agent_id}/rollouts”Start Experiment
Start a 2-5 arm A/B experiment, superseding whatever is currently running.
Requires ADMIN or OWNER role, and the platform’s agent_experiments_enabled
setting to be on (403 otherwise — a platform admin turns it on). Every arm
must resolve to a revision belonging to this agent (by version, id, or
use_draft for the current draft — sealed on start), pass the org’s
model allowlist, and have every tool/skill/knowledge-base grant resolve in
the org’s catalog and the agent’s own reach — the same checks
PATCH /agents/{id} runs, just for every arm instead of one config.
Weights must sum to 10 000 (basis points); control must name one of
the arm labels.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
| allow_identical | boolean | no | |
| arms | ExperimentArmRequest[] | yes | |
| control | string | yes | |
| hypothesis | string | no | |
| label | string | no | |
| unit | string | no |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | RolloutDetailResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}
Section titled “GET /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}”Get Rollout
One rollout’s arms (label, revision version, weight) and live per-arm chat counts.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes | |
| rollout_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutDetailResponse |
| 422 | Validation Error | HTTPValidationError |
PATCH /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}
Section titled “PATCH /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}”Update Rollout
Rename an experiment and/or edit its hypothesis.
Requires ADMIN or OWNER role. Partial: only the fields actually present in
the body change (null or "" clears them); the rollout must be an
experiment, not a plain deploy (409).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes | |
| rollout_id | path | string (uuid) | yes |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
| hypothesis | string | no | |
| label | string | no |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutDetailResponse |
| 422 | Validation Error | HTTPValidationError |
POST /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/promote
Section titled “POST /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/promote”Promote Experiment Arm
End the running experiment as promoted and deploy the named arm at 100%.
rollout_id must be the currently running experiment — 409 otherwise
(naming what is actually running, if anything). Requires ADMIN or OWNER role.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes | |
| rollout_id | path | string (uuid) | yes |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
| arm | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutDetailResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/results
Section titled “GET /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/results”Get Rollout Results
Per-arm results for one rollout: outcome distribution, cost, tokens,
tool-call and HITL rates, and duration — each with a 95% confidence
interval — plus each non-control arm’s delta vs the control arm and a
significant flag (intervals that don’t overlap). insufficient_data on
an arm means its counted chats are below the rollout’s min_sample;
every figure is still computed, just worth caveating in the UI.
Cost is reported in exactly one of credits/usd per billing_unit
— never both, matching every other spend-carrying response in this API.
Cached for about 45 seconds per rollout, so a page polling this while an experiment runs will see the same numbers for short bursts rather than re-running the full aggregation on every request.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes | |
| rollout_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutResultsResponse |
| 422 | Validation Error | HTTPValidationError |
POST /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/stop
Section titled “POST /api/orgs/{org_id}/agents/{agent_id}/rollouts/{rollout_id}/stop”Stop Experiment
End the running experiment as stopped and deploy the control revision at 100%.
rollout_id must be the currently running experiment. Requires ADMIN
or OWNER role.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | yes | |
| org_id | path | string (uuid) | yes | |
| rollout_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | RolloutDetailResponse |
| 422 | Validation Error | HTTPValidationError |