Agent Versions

Get an archived agent config version

Returns the exact configuration the agent held at a given version, so a generation can be traced back to the config that produced it.

get/v1/projects/{project_id}/agents/{agent_id}/versions/{version}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/agents/{agent_id}/versions/{version}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

agent_idstring required
Example:agent_V1StGXR8Z5jdHi6B

Agent public ID

versioninteger required

Archived config version number

Response

Archived agent version

idstring

Public ID of the archived version

agent_idstring

Public ID of the agent this version belongs to

versioninteger

The archived version number

configobject

The agent's configuration as it stood at this version: every mutable field of the Agent schema (instructions, model, tool_bindings, max_steps, tool_choice, stop_conditions, active_tool_ids, step_rules, boundary_policy, temperature, knowledge_config, output_schema, max_context_messages, max_output_tokens, reasoning, single_session_per_actor, on_approval_expiry, guardrail_ids, ai_provider_id, model_route_id, name), and none of its identity or bookkeeping fields (id, project_id, version, active_release, timestamps). A literal credential in an inline tool_bindings definition is masked as on the Agent read, and a restore or release of such a version is refused with 400 LITERAL_CREDENTIAL.

Deliberately open rather than a fixed schema: an archive written by an earlier release of the runtime reflects the agent surface of its own time, so it may carry fields the current schema no longer defines, or lack ones it has since gained. Knowledge retrieval is not part of the snapshot — a version records which knowledge_config applied, while the documents and memory stores it resolves keep their own histories and are pinned at generation time.

labelstring nullable

Optional human tag, set with version_label on the write that created this version. Restore, promote and abort set one automatically (e.g. restored from v1).

eval_run_idstring nullable

The eval run that cleared the release's promotion_gate when this version was promoted. Null for every version that did not go live through a gated promotion — which is most of them.

created_by_principal_type'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

created_by_principal_idstring nullable

Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.

created_atstring date-time

Example response

{
  "id": "agver_V1StGXR8Z5jdHi6B",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "version": 1,
  "label": "pre-tone-change",
  "eval_run_id": "evrun_V1StGXR8Z5jdHi6B",
  "created_by_principal_type": "user",
  "created_by_principal_id": "user_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.