> ## 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. # List an agent's immutable version history > Returns all immutable agent versions, newest to oldest, projected through the current public contract. Prompt, model, and supported capabilities remain visible; inert legacy tool declarations remain stored but are omitted from these responses. The response is not paginated. ## OpenAPI ````yaml /managed-agents/openapi.yaml get /managed-agents/v1/agents/{agent_id}/versions openapi: 3.1.0 info: title: Managed Agents API version: 0.14.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/{agent_id}/versions: get: tags: - Agents summary: List an agent's immutable version history description: >- Returns all immutable agent versions, newest to oldest, projected through the current public contract. Prompt, model, and supported capabilities remain visible; inert legacy tool declarations remain stored but are omitted from these responses. The response is not paginated. operationId: managedAgentsListAgentVersions parameters: - description: Agent id (UUID) as returned by createAgent or listAgents. in: path name: agent_id required: true schema: description: Agent id (UUID) as returned by createAgent or listAgents. format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsAgentVersionListResponse' description: >- Response body of GET /v1/agents/{agent_id}/versions. Scoped to the one agent in the path, so an empty list means that agent has no versions yet, not that no agents exist. Versions are immutable snapshots: pin one to make a session reproducible. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' '409': description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsApiErrorIosClientUpdateRequired '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' '500': description: An unexpected server-side failure. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' - $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation discriminator: propertyName: code mapping: internal_error: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' invariant_violation: $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': description: >- A dependency is unavailable. Consult details.retryable and Retry-After when present before retrying. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable '504': description: The service did not respond before the timeout. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsAgentVersionListResponse: description: >- Response body of GET /v1/agents/{agent_id}/versions. Scoped to the one agent in the path, so an empty list means that agent has no versions yet, not that no agents exist. Versions are immutable snapshots: pin one to make a session reproducible. properties: agent_versions: description: >- Every published version of the requested agent, newest first. Null rather than an empty array when the agent exists but has never been versioned. items: $ref: '#/components/schemas/ManagedAgentsAgentVersion' type: - array - 'null' required: - agent_versions type: object example: agent_versions: - agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d built_in_integrations: - connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d tools: [] created_at: '2026-02-18T09:30:00.000Z' created_by: example default_credential_refs: - credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d default_rubric: example default_vault_ids: - example description: example disabled_integration_mcp_providers: - example max_concurrent_sessions: 1 mcp_servers: - key: example metadata: key: example model: example model_config: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 multiagent: key: example name: example-name nativeIntegrations: - connectionId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d permission: example resources: - example organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d skills: - key: example system: example toolsets: - type: evaluation version_number: 1 web_search_enabled: true 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. ManagedAgentsApiErrorIosClientUpdateRequired: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - ios_client_update_required 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. ManagedAgentsApiErrorInvariantViolation: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invariant_violation 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. ManagedAgentsApiErrorBadGateway: 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. 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. ManagedAgentsApiErrorGatewayTimeout: 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. ManagedAgentsAgentVersion: description: >- An immutable snapshot of an agent's configuration, minted on every update. Sessions reference a version rather than the agent, so a running session's behaviour cannot change under it. properties: agent_id: description: Agent this version belongs to (UUID). type: string agent_version_id: description: >- Identifier for this agent version (UUID). Server-assigned. Pass it when starting a session that must run a specific version. type: string built_in_integrations: description: >- Built-in integrations sessions started from this version may use, each naming an organization connection an admin added. Snapshotted with the version. items: $ref: '#/components/schemas/ManagedAgentsBuiltInIntegration' type: array created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string created_by: description: >- User who made the edit that produced this version, for audit. Empty when the version was created by an automated caller. type: string default_credential_refs: description: Narrows this version's default vaults to individual credentials. items: $ref: '#/components/schemas/ManagedAgentsVaultCredentialRef' type: - array - 'null' default_rubric: description: >- Markdown rubric that sessions started from this version are graded against when their create request omits an outcome. A session that supplies its own outcome ignores this entirely. type: string default_vault_ids: description: >- Vaults whose credentials are copied into a new session started from this version when the create request omits vault_ids. items: type: string type: - array - 'null' description: description: The agent's free-text note as it stood at this version. type: string disabled_integration_mcp_providers: description: >- Native integration providers whose MCP tools sessions started from this version do not receive. The grant and its sandbox credentials are unaffected. items: type: string type: - array - 'null' max_concurrent_sessions: description: >- Maximum concurrent root sessions configured on the agent when this version was minted. Unset means unlimited. Live admission uses the agent head's current value, not this snapshot. maximum: 10000 minimum: 1 type: integer mcp_servers: description: >- Remote MCP servers attached at this version. Each entry is an object with name and url (http/https); further keys pass to the runtime unchanged. Credentials come from the session's granted vaults. items: additionalProperties: {} type: object type: - array - 'null' metadata: additionalProperties: {} description: >- Free-form caller-supplied key/value labels. Stored verbatim and never interpreted by the service. type: object model: description: >- Model this version runs on, in the same form as an agent's model: a models-catalog id such as anthropic/claude-sonnet-4-5, returned in its stored form with a provider prefix added. type: string model_config: $ref: '#/components/schemas/ManagedAgentsInferenceConfig' description: >- Default inference settings this version applies to every turn unless a session overrides them. multiagent: additionalProperties: {} description: >- Multi-agent orchestration settings at this version, such as subagent definitions and delegation limits. type: object name: description: The agent's human-readable label as it stood at this version. type: string nativeIntegrations: description: >- Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection. items: $ref: '#/components/schemas/ManagedAgentsNativeIntegration' maxItems: 25 type: array organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string skills: description: >- Skill packages loaded into the runtime at this version, each an entry with the skill reference and its metadata. items: additionalProperties: {} type: object type: - array - 'null' system: description: System prompt this version prepends to every conversation. type: string toolsets: description: >- The bare evaluation marker, when this is an evaluator version. Historical stored versions may contain ignored declarations, omitted from current API responses. Built-in sandbox tools need no marker. items: additionalProperties: false properties: type: description: The evaluation marker is the only supported toolset type. enum: - evaluation type: string required: - type type: object maxItems: 1 type: - array - 'null' version_number: description: >- Monotonically increasing version counter within the agent, starting at 1. Server-assigned. format: int64 type: integer web_search_enabled: default: true description: >- Whether sessions created from this version may use the native web_search tool. Omitted on legacy versions and interpreted as enabled. type: boolean required: - organization_id - agent_id - agent_version_id - version_number - name - system - toolsets - mcp_servers - default_vault_ids - default_credential_refs - disabled_integration_mcp_providers - skills - model_config - created_at type: object example: agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d built_in_integrations: - connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d tools: [] created_at: '2026-02-18T09:30:00.000Z' created_by: example default_credential_refs: - credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d default_rubric: example default_vault_ids: - example description: example disabled_integration_mcp_providers: - example max_concurrent_sessions: 1 mcp_servers: - key: example metadata: key: example model: example model_config: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 multiagent: key: example name: example-name nativeIntegrations: - connectionId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d permission: example resources: - example organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d skills: - key: example system: example toolsets: - type: evaluation version_number: 1 web_search_enabled: true 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: {} description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. ManagedAgentsBuiltInIntegration: description: >- One built-in integration an agent may use, named by its organization connection. The connection carries the app and the tools its agents may call; the agent inherits both. properties: connection_id: description: >- Organization integration connection (UUID) the agent may use. Must belong to the caller's organization, be a built-in integration connection, and be active. type: string tools: description: >- Reserved for per-agent narrowing below the connection's admin allow-list. Must be omitted or empty today; the agent inherits the connection's full allow-list. items: type: string maxItems: 0 type: array required: - connection_id type: object example: connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d tools: [] ManagedAgentsVaultCredentialRef: description: >- A pointer to one credential inside one vault. Used to grant a session specific credentials rather than every credential in a vault. properties: credential_id: description: Credential to select inside vault_id. type: string vault_id: description: >- Vault holding the credential. Required, because credential ids are unique only within a vault. type: string required: - vault_id - credential_id type: object example: credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsInferenceConfig: description: >- Sampling and generation settings for a model call, mirroring the provider's own request parameters. Set it on an agent or a session to govern every turn, and read it back on a model event to see what the call actually used. properties: max_tokens: description: >- Upper bound on tokens the model may generate for one assistant turn (the provider's max_tokens). Omit or 0 to use the model reference's default. format: int64 type: integer provider_params: additionalProperties: {} description: >- Extra provider request parameters merged into the inference call for options this schema does not model. Keys are provider-specific and are passed through unvalidated. type: object reasoning_effort: description: >- Provider-native reasoning depth value. For a model from the models catalog, use one of its supportedReasoningEfforts; omit it to follow the provider's current default. type: string temperature: description: >- Sampling temperature passed through to the provider, typically 0.0-2.0. Lower values are more deterministic. Omit to use the provider default. type: number top_p: description: >- Nucleus-sampling probability mass (0.0-1.0) passed through to the provider. Prefer setting either this or temperature, not both. Omit to use the provider default. type: number type: object example: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 ManagedAgentsNativeIntegration: description: >- A native connection and its agent-owned runtime permission and resource policy. properties: connectionId: description: Active native connection in this organization. format: uuid type: string permission: description: >- Provider permission preset, bounded by the connection's authorization. type: string resources: description: >- Optional resource subset. Omit to inherit all resources available through the connection. An explicit empty list is rejected. items: type: string maxItems: 500 minItems: 1 type: array uniqueItems: true required: - connectionId - permission type: object example: connectionId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d permission: example resources: - example securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````