> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Move an agent's live sessions to its latest version > Starts a background upgrade that asks every live root session of the agent the caller may change -- active, queued, idle or awaiting a person -- to move to the agent's latest version, pinned when the request is accepted. It returns 202 at once with the upgrade; follow it with managedAgentsGetAgentSessionUpgrade. Each session is moved exactly as managedAgentsReplaceSessionAgentVersion moves one, and the move takes effect before that session's next model call. A move brings the session's instructions, model and inference settings, tools, MCP servers, skills, integrations, credentials and roster to the new version, tells the agent what changed, and moves an outcome the session inherited from the agent's default rubric to the new version's default; an outcome the caller supplied, or one already graded, is left as it is. Sessions that cannot move are counted as skipped with a reason and left as they are. One upgrade runs per agent at a time, and upgrades of different agents run side by side: repeating the request while the agent's upgrade runs returns the running upgrade and starts nothing. An agentId that names no agent of the caller's organization answers 404, and an agent with no version answers 409 conflict. Requires an Idempotency-Key header: the same key with the exact HTTP method, escaped path, raw query, and raw body bytes replays the original 202; any difference is rejected. The caller needs both managed-agents:create and managed-agents:update. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/agents/{agentId}/upgrade-sessions openapi: 3.1.0 info: title: Managed Agents API version: 0.15.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/agents/{agentId}/upgrade-sessions: post: tags: - Sessions summary: Move an agent's live sessions to its latest version description: >- Starts a background upgrade that asks every live root session of the agent the caller may change -- active, queued, idle or awaiting a person -- to move to the agent's latest version, pinned when the request is accepted. It returns 202 at once with the upgrade; follow it with managedAgentsGetAgentSessionUpgrade. Each session is moved exactly as managedAgentsReplaceSessionAgentVersion moves one, and the move takes effect before that session's next model call. A move brings the session's instructions, model and inference settings, tools, MCP servers, skills, integrations, credentials and roster to the new version, tells the agent what changed, and moves an outcome the session inherited from the agent's default rubric to the new version's default; an outcome the caller supplied, or one already graded, is left as it is. Sessions that cannot move are counted as skipped with a reason and left as they are. One upgrade runs per agent at a time, and upgrades of different agents run side by side: repeating the request while the agent's upgrade runs returns the running upgrade and starts nothing. An agentId that names no agent of the caller's organization answers 404, and an agent with no version answers 409 conflict. Requires an Idempotency-Key header: the same key with the exact HTTP method, escaped path, raw query, and raw body bytes replays the original 202; any difference is rejected. The caller needs both managed-agents:create and managed-agents:update. operationId: managedAgentsStartAgentSessionUpgrade parameters: - description: >- Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents. in: path name: agentId required: true schema: description: >- Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents. format: uuid type: string - description: >- 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. in: header name: Idempotency-Key required: true schema: description: >- 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. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '202': content: application/json: schema: $ref: '#/components/schemas/SessionAgentVersionUpgrade' description: >- A request to move every live root session of one agent to that agent's latest version, and how far it has come. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple Location: description: Relative URL of the created or admitted resource. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '409': headers: Retry-After: description: >- When present, delay in seconds or an HTTP-date after which the caller may retry; absence supplies no retry advice. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Conflict. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress discriminator: propertyName: code mapping: conflict: '#/components/schemas/ManagedAgentsApiErrorConflict' idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress x-recursion-error-codes: - conflict - idempotency_conflict - idempotency_in_progress '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - idempotency_unavailable - managed_agents_unavailable - service_unavailable headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- 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`. schema: type: string minLength: 1 schemas: SessionAgentVersionUpgrade: additionalProperties: false description: >- A request to move every live root session of one agent to that agent's latest version, and how far it has come. properties: agentId: description: The agent whose sessions this upgrade moves. format: uuid type: string agentVersionId: description: >- The agent's latest version when the upgrade was accepted: the version every session is asked to move to. format: uuid type: string counts: $ref: '#/components/schemas/SessionAgentVersionUpgradeCounts' description: Sessions handled so far, by outcome. finishedAt: description: When the upgrade completed or was cancelled, or null while it runs. format: date-time type: - 'null' - string issues: description: >- 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. items: $ref: '#/components/schemas/SessionAgentVersionUpgradeIssue' maxItems: 50 type: array requestedAt: description: When the upgrade was accepted. format: date-time type: string requestedByUserId: description: >- User who requested the upgrade. Absent when no user made the request. type: string state: description: >- 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. enum: - running - completed - cancelled type: string statusUrl: description: >- Path of the upgrade's status resource, where managedAgentsGetAgentSessionUpgrade reads it. type: string upgradeId: description: Identifier of this upgrade. format: uuid type: string required: - upgradeId - agentId - agentVersionId - statusUrl - state - requestedAt - finishedAt - counts - issues type: object ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. SessionAgentVersionUpgradeCounts: additionalProperties: false properties: alreadyCurrent: description: Sessions already running the new version with nothing pending. format: int64 minimum: 0 type: integer maximum: 9007199254740991 failed: description: >- Sessions that could not be asked for a passing reason. A later upgrade asks them again. format: int64 minimum: 0 type: integer maximum: 9007199254740991 requested: description: >- Sessions now set to run the new version. Each adopts it before its next model call, or reports why it could not on managedAgentsGetSessionAgentVersion. format: int64 minimum: 0 type: integer maximum: 9007199254740991 scanned: description: 'Live root sessions handled so far: the sum of the other counts.' format: int64 minimum: 0 type: integer maximum: 9007199254740991 skipped: description: >- Sessions that cannot move, such as platform-run sessions, evaluations, pull request reviews, sessions stopping, or sessions whose agent was deleted. Asking again gives the same answer. format: int64 minimum: 0 type: integer maximum: 9007199254740991 required: - scanned - requested - alreadyCurrent - skipped - failed type: object SessionAgentVersionUpgradeIssue: additionalProperties: false properties: code: description: >- Stable reason, such as conflict, not_found or temporarily_unavailable. The list may grow; clients must accept values not listed here. type: string message: description: One platform sentence explaining the outcome. type: string outcome: description: Whether the session was skipped or could not be asked. enum: - skipped - failed type: string sessionId: description: The session. format: uuid type: string required: - sessionId - outcome - message type: object ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````