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

# Agent configuration versions

> Read version history, compare versions, inspect the current route, and restore a previous version.

These account routes expose the current Orchestration Studio version and route behavior. They require authentication as an account administrator and the account's `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 an `Idempotency-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:

```json theme={null}
{
  "version": "7fb6e99a-e292-427c-a9d9-19325fabf929",
  "request_id": "4499d018-dbc0-4700-93d2-d08610c7cf0a"
}
```

The request ID makes this command replayable. An `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.