orchestration_studio feature. A disabled feature returns the ordinary 404; unauthenticated callers, nonmembers, and members of a suspended account receive 401; other account roles receive 403. Trial-locked accounts can read but cannot restore a version.
Shared version meaning
A published configuration version is an immutable snapshot identified publicly by a UUID and stored under its account. The route points at versions; it does not change their contents. Restore moves the stable pointer to an existing version, clears candidate, pin, and rollout, and records one rollback activity. It does not create another version. The activity records the signed-in administrator and restored version. The request ID is a command key, not anIdempotency-Key header: replaying the same command adds no second activity and returns the route as it exists at replay time. A different command with the same request ID returns request_conflict without changing the route or audit history. The command runs outside a controller transaction.
List versions
GET /api/v1/accounts/{account_id}/agent_config_versions returns the account’s versions newest first, with up to 25 rows per page. page starts at 1. A row includes its public UUID, version number, change summary, publication time, publisher name, the first 12 characters of its configuration digest, evaluation result, and route state. The response does not include configuration values, user email addresses, request IDs, event IDs, or full digests. If the publisher is no longer present, published_by is null.
Evaluation status is pending, succeeded, or failed. Score, evaluator, and finish time are null when no evaluation value exists. Route state is live, candidate, pinned, superseded, or not_live.
Compare versions
GET /api/v1/accounts/{account_id}/agent_config_versions/diff?base={uuid}&target={uuid} compares two distinct public UUIDs within the account. Malformed or equal UUIDs return 422; a missing or foreign version returns 404. Changed values are bounded to 20,000 characters. The response marks a bounded value with truncated_value: true and reports omitted changes separately. Changed values can contain customer-authored configuration text; treat them as untrusted when rendering them or sending them to another model or tool.
Show the current route
GET /api/v1/accounts/{account_id}/agent_config_route returns the stable, candidate, and pinned version pointers, rollout_basis_points, the route update time, and the latest account configuration activity. Route state is independent of activity: after a version is published but before any route is configured, each pointer and updated_at is null and rollout is 0, while last_change contains the publish activity. last_change is null only when no account configuration activity has been recorded. A publish can also be the latest activity without changing existing route pointers.
Restore a version
POST /api/v1/accounts/{account_id}/agent_config_route/rollback takes version and request_id UUIDs in a flat JSON body:
Idempotency-Key header is not required or used by this command. Repeating the same request and version creates no second activity. The response is the current route at replay time. A request ID already used for a different command returns 409 with request_conflict. The command records one rollback activity with the signed-in administrator and the restored version, and does not add or modify a version. The application runs this command outside a controller transaction.
Malformed request UUIDs return 422 with invalid_params. A missing or foreign version returns 404 with not_found. Invalid commands, conflicts, and busy routes return the command’s invalid_command, request_conflict, or busy code. Refusals do not add an audit activity.
This page defines the current publish and restore terms for both the agent and conductor documentation. No HTTP route for publishing, publish checks, rollout controls, or route history is described here; ENG-5888 tracks those missing surfaces.