Skip to main content
POST
Move an agent's live sessions to its latest version

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string
required

Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

agentId
string<uuid>
required

Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents.

Response

A request to move every live root session of one agent to that agent's latest version, and how far it has come.

A request to move every live root session of one agent to that agent's latest version, and how far it has come.

agentId
string<uuid>
required

The agent whose sessions this upgrade moves.

agentVersionId
string<uuid>
required

The agent's latest version when the upgrade was accepted: the version every session is asked to move to.

counts
object
required

Sessions handled so far, by outcome.

finishedAt
null | string<date-time>
required

When the upgrade completed or was cancelled, or null while it runs.

issues
object[]
required

Up to 50 sessions the upgrade skipped or could not ask, in the order it met them. The counts are complete; this list is a sample.

Maximum array length: 50
requestedAt
string<date-time>
required

When the upgrade was accepted.

state
enum<string>
required

running: sessions are still being asked to move. completed: every live root session in scope has been asked. cancelled: the upgrade was stopped; sessions it had already asked still move.

Available options:
running,
completed,
cancelled
statusUrl
string
required

Path of the upgrade's status resource, where managedAgentsGetAgentSessionUpgrade reads it.

upgradeId
string<uuid>
required

Identifier of this upgrade.

requestedByUserId
string

User who requested the upgrade. Absent when no user made the request.