Skip to content
Everruns Everruns

List saved agent versions

GET
/v1/agents/{agent_id}/versions
 
curl --request GET \
  --url https://app.everruns.com/api/v1/agents/example/versions

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
agent_id
required
string

Agent ID (prefixed) or name

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Saved agent versions

Media type application/json
Array<object>

Immutable snapshot of an Agent’s authored and resolved runtime config.

object
agent_id
required

Owning agent’s prefixed public identifier.

string
authored_config
required

User-authored agent configuration JSON, exactly as submitted. Capabilities, MCP refs, model selection live here.

object
change_kind
required

Classification of why this version was created (manual publish, automatic draft, rollback, fork, etc.).

string
Allowed values: auto manual patch minor major import rollback fork
config_hash
required

Stable hash of resolved_config used to deduplicate adjacent identical snapshots.

string
created_at
required

Timestamp when this version was created (RFC 3339).

string format: date-time
created_by_principal_id

Identity of the principal (user or agent identity) that created this version. None for system-generated snapshots.

string | null
id
required

Prefixed public identifier. See ID Schema.

string
is_published
required

Whether this version was explicitly published by a user. Published versions are user-controlled semver releases; unpublished rows are automatic draft snapshots kept for audit and rollback.

boolean
parent_version_id

Version this one was forked or branched from, if any.

string | null
resolved_config
required

Resolved configuration after applying harness, capability, and platform layers. This is what the runtime executes against.

object
semver_major
required

Semantic version major component.

integer format: int32
semver_minor
required

Semantic version minor component.

integer format: int32
semver_patch
required

Semantic version patch component.

integer format: int32
source_version_id

When this version is a copy of another version (e.g. a manual rollback), the original source. None for ordinary snapshots.

string | null
summary

Human-readable summary of changes in this version (release notes). None if not provided.

string | null
version
required

Combined semver string for display (e.g. 1.4.2).

string
version_number
required

Monotonic per-agent version sequence number (1, 2, 3, …). Increments on every snapshot.

integer format: int32
Example 
[
  {
    "agent_id": "agent_01933b5a000070008000000000000001",
    "change_kind": "auto",
    "config_hash": "blake3:9f1e2a4c3d5b6e8a0b2c4d6e8f0a1b3c5d7e9f0a1b2c4d6e8f0a1b2c4d6e8f0a",
    "created_at": "2026-04-20T14:22:00Z",
    "id": "agentver_01933b5a000070008000000000000001",
    "is_published": true,
    "semver_major": 1,
    "semver_minor": 4,
    "semver_patch": 2,
    "summary": "Switched default model to claude-sonnet-4-6; added refund-runbook capability.",
    "version": "1.4.2",
    "version_number": 7
  }
]

404

Section titled “404 ”

Agent not found or agent_versions disabled

Media type application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null
Example 
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}