Get an agent definition version

GET

/api/agent-definitions/versions/{versionId}

• Production

Returns a single agent definition version, including its captured configuration and audit metadata. Version rows are immutable and survive deletion of the parent agent.

Authorizations

• bearerAuth

Parameters

Path Parameters

versionId

required

string format: uuid

The unique identifier of the version to retrieve.

Responses

200

The version was found and returned.

A single published, superseded, or rejected version of an agent definition. Restoring a version creates a new published version rather than mutating history.

object

id

required

Unique identifier for this version row.

string format: uuid

Example

v1a2b3c4-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this version belongs to. Agent versions always belong to a tenant.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

agentId

required

The agent definition this version belongs to.

string format: uuid

Example

ag1a2b3c-5678-9abc-def0-1234567890ab

versionNumber

required

Monotonic version number within the agent, starting at 1.

integer

Example

3

status

required

Lifecycle status of this version. ‘published’ is the currently active version, ‘superseded’ is a former published version, ‘draft’ and ‘pending_review’ are unpublished work, ‘rejected’ was declined in review.

string

Allowed values: draft pending_review published superseded rejected

Example

published

sessionId

The change-set session that produced this version, when one applies.

string | null format: uuid

displayName

required

Human-readable agent name captured in this version.

string

Example

Shipping Tracker

description

required

Agent description captured in this version.

string

Example

Looks up shipping status and tracking information.

agentRole

required

The agent role captured in this version, such as ‘specialist’.

string

Example

specialist

roleSlug

required

Stable slug identifying the agent role.

string

Example

shipping-tracker

model

The model identifier captured in this version. Null when the platform default is used.

string | null

systemPrompt

System prompt captured in this version, when set.

string | null

requiredCapabilities

required

Capabilities the agent requires, captured in this version.

Array<string>

Example

[
  "mcp:call"
]

customInstructions

Custom instructions captured in this version, when set.

string | null

maxIterations

required

Maximum tool-use iterations captured in this version.

integer

Example

6

mcpAttachments

required

The connection and allowed-tool bindings captured in this version.

Array<object>

object

connectionId

required

Reference to a connection.

string format: uuid

Example

mc1a2b3c-5678-9abc-def0-1234567890ab

allowedTools

required

Tool names the agent may call on the connection.

Array<string>

Example

[
  "get_shipment_status"
]

authorUserId

Identifier of the actor who authored this version, or an api-key actor reference when created programmatically.

string | null

Example

kp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

authorNote

Optional note the author attached to this version.

string | null

Example

Corrected the delivery estimate for Germany.

sourceType

required

How this version was produced. Values include ‘manual’, ‘backfill’, ‘restore’, and ‘sandbox_apply’.

string

Example

manual

sourceSessionId

The originating session when this version was produced by an applied change-set.

string | null format: uuid

sourceConversationId

The conversation that inspired this version, when it originated from a resolved conversation.

string | null format: uuid

predecessorVersionId

The version this one succeeds. Null for the first version.

string | null format: uuid

publishedAt

Timestamp when this version became published. Null while unpublished.

string | null format: date-time

Example

2026-03-15T10:30:00.000Z

supersededAt

Timestamp when this version was superseded by a newer one. Null while current.

string | null format: date-time

rejectedAt

Timestamp when this version was rejected in review, when applicable.

string | null format: date-time

rejectionReason

Reason recorded when the version was rejected in review.

string | null

createdAt

required

Timestamp when this version row was created.

string format: date-time

Example

2026-03-15T10:30:00.000Z

updatedAt

required

Timestamp when this version row was last updated.

string format: date-time

Example

2026-03-15T10:30:00.000Z

404

No agent definition version exists with the given ID in the authenticated tenant.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found