List Agent Versions

GET/v1/agents/{agent_id}/versions

List the version history of an agent. Each update that changes the configuration creates a new version snapshot; no-op updates do not. Returns the snapshots newest-first.

Path Parameters

Parameter	Type	Required	Description
agent_id	string	✅	The agent ID (agent_...)

Query Parameters

Parameter	Type	Required	Description
limit	integer	❌	Page size. Default 20, max 100.
page	string	❌	Opaque cursor from a previous response's next_page.

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

page = client.beta.agents.versions.list(agent_id="agent_01HqR2k7...")
for v in page.data:
    print(f"v{v.version} — {v.created_at}")

cURL

curl https://api.sandbase.ai/v1/agents/agent_01HqR2k7.../versions \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Response

Each item is a version snapshot: the agent's version number, the created_at of that revision, and the full configuration snapshot captured at that version.

{
  "data": [
    {
      "id": "agver_02def...",
      "agent_id": "agent_01HqR2k7...",
      "version": 2,
      "snapshot": {
        "name": "Research Assistant",
        "model": { "id": "claude-sonnet-4", "speed": "standard" },
        "system": "You are a senior research assistant. Always cite sources.",
        "tools": [{ "type": "agent_toolset_20260401" }],
        "mcp_servers": []
      },
      "created_at": "2026-05-29T11:00:00Z"
    },
    {
      "id": "agver_01abc...",
      "agent_id": "agent_01HqR2k7...",
      "version": 1,
      "snapshot": {
        "name": "Research Assistant",
        "model": { "id": "claude-sonnet-4", "speed": "standard" },
        "system": "You are a research assistant...",
        "tools": [{ "type": "agent_toolset_20260401" }],
        "mcp_servers": []
      },
      "created_at": "2026-05-29T10:00:00Z"
    }
  ]
}

Version Snapshot

Field	Type	Description
id	string	Version record ID
agent_id	string	The agent this version belongs to
version	integer	Version number (starts at 1, increments on change)
snapshot	object	Full agent configuration captured at this version
created_at	string	RFC 3339 timestamp of the revision

To fetch a specific version as a full Agent object, use Get Agent with ?version=N.

Pagination

Results are ordered by version descending. When more results exist, the response includes a next_page cursor; pass it back as the page parameter.

Errors

Status	Type	Description
401	authentication_error	Invalid or missing API key
404	not_found	Agent not found