> ## 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 a page of an agent's immutable versions, newest first. Follow nextCursor until null. A newly published version can appear ahead of a cursor and will be included on a fresh listing. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v2/agents/{agentId}/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/v2/agents/{agentId}/versions: get: tags: - Agents summary: List an agent's immutable version history description: >- Returns a page of an agent's immutable versions, newest first. Follow nextCursor until null. A newly published version can appear ahead of a cursor and will be included on a fresh listing. operationId: managedAgentsListAgentVersionsV2 parameters: - description: Maximum versions per page, default 50. in: query name: limit schema: default: 50 description: Maximum versions per page, default 50. maximum: 100 minimum: 1 type: integer - description: Opaque nextCursor from the previous page with the same limit. in: query name: cursor schema: description: Opaque nextCursor from the previous page with the same limit. type: string - 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 - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandaloneAgentVersionListResponse' description: OK headers: 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' '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' '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': 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: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - managed_agents_unavailable - service_unavailable '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: StandaloneAgentVersionListResponse: additionalProperties: false properties: items: description: >- One page of published versions of the requested agent, newest first, with server-authored execution compatibility. items: $ref: '#/components/schemas/StandaloneAgentVersion' type: array nextCursor: description: Opaque cursor for the next page, or null at the end. type: - 'null' - string total: description: Number of published versions of the requested agent. format: int64 minimum: 0 type: integer maximum: 9007199254740991 required: - items - nextCursor - total 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. 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. 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. 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. StandaloneAgentVersion: description: >- An immutable snapshot of a standalone Managed Agent's configuration. Sessions reference a version so a running session cannot change under them. properties: agentId: description: Agent this version belongs to (UUID). type: string agentVersionId: description: >- Identifier for this agent version (UUID). Server-assigned. Pass it when starting a session that must run a specific version. type: string builtInIntegrations: 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/BuiltInIntegration' type: array createdAt: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string createdBy: description: >- User who made the edit that produced this version, for audit. Empty when the version was created by an automated caller. type: string defaultCredentialRefs: description: Narrows this version's default vaults to individual credentials. items: $ref: '#/components/schemas/VaultCredentialRef' type: array defaultProjectId: description: >- Billing project copied into sessions started from this version when their create request omits project_id. A non-empty session project_id overrides it. type: string defaultRubric: description: >- Markdown rubric that sessions started from this version are graded against by default when they start with a message. A session that supplies its own outcome ignores this entirely. type: string defaultVaultIds: 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 description: description: The agent's free-text note as it stood at this version. type: string disabledIntegrationMcpProviders: description: >- Native integration providers whose MCP tools sessions started from this version do not receive. github is ignored, because a GitHub grant always keeps its MCP tools alongside git and gh in the sandbox. items: type: string type: array executionCompatibility: description: >- Whether this exact immutable version is compatible with the standalone execution context. Omitted by deployments that do not compute it; a client must treat any present value other than compatible as incompatible. enum: - compatible - incompatible type: string fileHistoryEnabled: description: >- Whether sessions created from this version may search and read the session outputs this agent's earlier sessions saved. Omitted means off. type: boolean maxConcurrentSessions: 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. Outcome evaluation passes do not take a slot. maximum: 10000 minimum: 1 type: integer mcpServers: 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: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object type: array metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Free-form caller-supplied key/value labels. Stored verbatim and never interpreted by the service. type: object model: description: >- Public model id this version runs on, in the same form as an agent's model. type: string modelConfig: $ref: '#/components/schemas/InferenceConfig' description: >- Default inference settings this version applies to every turn unless a session overrides them. multiagent: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' 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/NativeIntegration' maxItems: 25 type: array organizationId: description: >- Organization that owns this record. Resolved from the authenticated principal; 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: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object type: array supportsNewSessions: description: >- Whether this version's agent type supports new sessions here. Other start requirements still apply. Existing sessions and version history remain available when false. type: boolean system: description: System prompt this version prepends to every conversation. type: string template: $ref: '#/components/schemas/TemplateRef' description: Reviewed template revision this version started from. versionNumber: description: >- Monotonically increasing version counter within the agent, starting at 1. Server-assigned. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 webSearchEnabled: 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: - organizationId - agentId - agentVersionId - versionNumber - name - system - mcpServers - defaultVaultIds - defaultCredentialRefs - disabledIntegrationMcpProviders - skills - modelConfig - createdAt type: object additionalProperties: false 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. BuiltInIntegration: description: >- One built-in integration an agent may use, named by its organization connection. The agent may narrow the connection's organization tool allow-list. 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: >- Optional subset of the connection's organization tool allow-list. Omit or send an empty list to inherit all organization-enabled tools. A non-empty list limits this agent to exactly those tools, subject to later organization changes. items: type: string maxItems: 200 type: array required: - connection_id type: object additionalProperties: false VaultCredentialRef: 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 additionalProperties: false 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 InferenceConfig: 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 minimum: -9007199254740991 maximum: 9007199254740991 provider_params: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Recognized provider-specific settings are thinking, thinkingDisplay and output_config for native Anthropic messages; thinkingConfig for native Gemini; and promptCache, promptCacheTTL and promptCacheSharedTTL for prompt caching. Unknown top-level keys are ignored, not passed through. Omitting all three cache settings enables automatic policy: explicit caching stays enabled and eligible Anthropic requests may use 1h shared retention when recent usage and current pricing evidence predict savings; otherwise shared retention is 5m. Setting promptCache or either TTL explicitly keeps operator-configured retention. promptCache true enables explicit markers; false disables them and ignores both TTL settings. With caching enabled, both TTL settings accept only 5m or 1h on models using native Anthropic messages. promptCacheTTL defaults to 5m for user-context anchors and history. promptCacheSharedTTL controls tools and system instructions, defaults to promptCacheTTL under explicit configuration, and cannot be shorter than promptCacheTTL. Authored thinking objects and enabled cache TTL settings are validated at agent/version writes and session start. 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 additionalProperties: false NativeIntegration: 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 tools: description: >- Standalone GitHub or Slack MCP tools this agent may use. Omit on existing grants to retain the prior tool access; new standalone grants select tools explicitly. An explicit empty list is rejected. items: type: string maxItems: 200 minItems: 1 type: array uniqueItems: true required: - connectionId - permission type: object additionalProperties: false TemplateRef: description: Reviewed template id and revision copied into this resource. properties: id: description: Stable template id. type: string revision: description: Reviewed catalog revision. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision type: object additionalProperties: false 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. ````