> ## 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. # Open the organization assistant > Returns the caller's organization assistant, starting one if they have none (created is true when this call started it): an assistant session that knows the platform's capabilities and the organization's agents, environments, skills and connections, and helps design, set up and check agents. It changes nothing by itself: it asks typed questions, presents solution blueprints and proposes plans, and only a plan the caller approves with managedAgentsSubmitAssistantInteractionDecision is executed, under the caller's own permissions. Talk to it with managedAgentsSendSessionEvents and read its events. One assistant per caller; {"reset": true} ends it. Calls not made on behalf of a person get 403. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/assistant 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/assistant: post: tags: - Sessions summary: Open the organization assistant description: >- Returns the caller's organization assistant, starting one if they have none (created is true when this call started it): an assistant session that knows the platform's capabilities and the organization's agents, environments, skills and connections, and helps design, set up and check agents. It changes nothing by itself: it asks typed questions, presents solution blueprints and proposes plans, and only a plan the caller approves with managedAgentsSubmitAssistantInteractionDecision is executed, under the caller's own permissions. Talk to it with managedAgentsSendSessionEvents and read its events. One assistant per caller; {"reset": true} ends it. Calls not made on behalf of a person get 403. operationId: managedAgentsOpenAssistant parameters: - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/OpenAssistantRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SessionAnalystResponse' description: >- Response body of managedAgentsOpenSessionAnalyst: the caller's read-only analyst session over a session tree, if there is one, and whether it was just started. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - 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: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartNotAdmitted - $ref: >- #/components/schemas/ManagedAgentsApiErrorWorkspaceBoundaryDenied discriminator: propertyName: code mapping: forbidden: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' session_start_not_admitted: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartNotAdmitted workspace_boundary_denied: $ref: >- #/components/schemas/ManagedAgentsApiErrorWorkspaceBoundaryDenied x-recursion-error-codes: - forbidden - session_start_not_admitted - workspace_boundary_denied 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': description: Conflict. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' discriminator: propertyName: code mapping: conflict: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' revision_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorRevisionConflict x-recursion-error-codes: - conflict - revision_conflict 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' '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 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: Too Many Requests. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded - $ref: >- #/components/schemas/ManagedAgentsApiErrorTenantConcurrencyLimit discriminator: propertyName: code mapping: rate_limit_exceeded: $ref: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded tenant_concurrency_limit: $ref: >- #/components/schemas/ManagedAgentsApiErrorTenantConcurrencyLimit x-recursion-error-codes: - rate_limit_exceeded - tenant_concurrency_limit '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/ManagedAgentsApiErrorContentStoreUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable - $ref: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystBusy - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystModelUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable discriminator: propertyName: code mapping: content_store_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable model_gateway_metadata_missing: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing model_gateway_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured model_gateway_unreachable: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable persistence_busy: $ref: >- #/components/schemas/ManagedAgentsApiErrorPersistenceBusy service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable session_analyst_busy: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystBusy session_analyst_model_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystModelUnavailable session_analyst_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystUnconfigured session_start_admission_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable x-recursion-error-codes: - content_store_unconfigured - managed_agents_unavailable - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - persistence_busy - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_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: OpenAssistantRequest: description: >- Request body of managedAgentsOpenAgentAnalyst and managedAgentsOpenAssistant. An empty object returns the caller's conversation, if any; question asks (starting the conversation if needed); reset ends the current conversation. properties: question: description: >- A question for the assistant. Starts the caller's conversation when there is none, as its first turn; otherwise it is delivered to the existing conversation. Omitted, nothing is asked. type: string x-recursion-omission: strategy: absent reset: default: false description: >- When true, ends the caller's current conversation: the assistant session is cancelled and stays readable, and the caller has no conversation until the next question. type: boolean type: object additionalProperties: false SessionAnalystResponse: description: >- Response body of managedAgentsOpenSessionAnalyst: the caller's read-only analyst session over a session tree, if there is one, and whether it was just started. properties: created: description: >- True when this call started the analyst; false when it returned the caller's existing conversation with this tree, or none. type: boolean session: $ref: '#/components/schemas/Session' description: >- The analyst session, when the caller has a conversation with this tree. Send questions to it with managedAgentsSendSessionEvents and read answers from its events; its kind is session_analyst and its access policy platform_internal. Absent when nothing has been asked yet, or the conversation was just reset: a question starts one. required: - created type: object additionalProperties: false ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json 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. 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. ManagedAgentsApiErrorSessionStartNotAdmitted: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_start_not_admitted 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. ManagedAgentsApiErrorWorkspaceBoundaryDenied: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - workspace_boundary_denied 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. ManagedAgentsApiErrorRevisionConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - revision_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. 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. ManagedAgentsApiErrorTenantConcurrencyLimit: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - tenant_concurrency_limit 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. ManagedAgentsApiErrorContentStoreUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_unconfigured 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. ManagedAgentsApiErrorModelProviderMetadataMissing: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_metadata_missing 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. ManagedAgentsApiErrorModelProviderUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_unconfigured 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. ManagedAgentsApiErrorModelProviderUnreachable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_unreachable 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. ManagedAgentsApiErrorPersistenceBusy: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - persistence_busy 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. ManagedAgentsApiErrorSessionAnalystBusy: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_busy 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. ManagedAgentsApiErrorSessionAnalystModelUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_model_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. ManagedAgentsApiErrorSessionAnalystUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_unconfigured 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. ManagedAgentsApiErrorSessionStartAdmissionUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_start_admission_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. Session: description: >- One durable agent run: its lifecycle status (active, awaiting_human, completed, failed, cancelled), the agent version, environment, model, and credentials it was pinned to, and its place in a multi-agent tree. Returned when starting, reading, or listing sessions; imported RL rollouts appear as sessions too and run no agent loop. properties: access_policy: type: string enum: - platform_internal description: >- Present only when reading a platform-managed session directly; these sessions are omitted from session lists. active_handoff: $ref: '#/components/schemas/ActiveHandoff' description: >- Current browser handoff, including its exclusive driver claim and deadline. Absent when no browser handoff is active. Never contains the short-lived access URL. agent_id: description: >- Agent this session runs (UUID). Empty for imported sessions that were not started from an agent. type: string agent_snapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The agent version's definition as it stood when the session started, frozen so later edits to the agent cannot change this session's behavior. type: object agent_version_id: description: >- Agent version this session runs (UUID), pinned at start so a later edit to the agent cannot change a running session. type: string computer_use: description: >- Whether this session has a computer-enabled environment and a display that passed its readiness probe. type: boolean concurrency_slot_held: description: >- Whether this root session currently occupies the agent's max_concurrent_sessions slot. True while admitted and non-terminal. False exclusively while an active queued root waits to start. Omitted for unlimited agents, child sessions, legacy rows, and terminal or deleted sessions. type: boolean config: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Resolved per-session runtime settings written at start, including the snapshotted MCP servers and tool bindings, multi-agent roster, and delegation depth limits. Read-only to callers. type: - object - 'null' created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string credential_refs: description: >- Explicit allowlist of individual credentials the session may use; null or empty when none are listed. Read credential_refs_configured to tell an intentionally empty allowlist from a legacy session granted whole vaults. items: $ref: '#/components/schemas/VaultCredentialRef' type: - array - 'null' x-recursion-nullable-collection: null-is-domain-value credential_refs_configured: description: >- True when credential_refs is an explicit allowlist. False on legacy sessions granted every credential in their vaults, which would otherwise be indistinguishable from an empty allowlist. type: boolean effective_model: description: >- Provider-qualified model string frozen for this session, including any per-session model override. Prefer this over resolving model_ref_id or the current agent version when displaying what actually ran. type: string environment_id: description: Environment whose sandbox definition this session runs in (UUID). type: string execution_state: description: >- Where the agent loop is. Empty for sessions without a loop, such as imported rollouts. provisioning normally clears in under a minute and is bounded: a sandbox that does not become ready within the deployment's compute-ready timeout (five minutes by default) fails the session with sandbox_provision_timeout, so a session is never stuck here indefinitely. This field, read from the session itself, is the authoritative status -- a session's event stream is written on a separate path and can lag it, so an empty event list does not mean the session is still starting. When a session leaves provisioning by failing, failure carries the reason. enum: - provisioning - queued - running - idle - completed type: string external_source_id: description: >- Identifier of the session's counterpart in the external_source_type system, so a caller can find the session again from that side. Set together with external_source_type. type: string external_source_type: description: >- Kind of external system this session is correlated to, e.g. slack_thread. Set together with external_source_id and filterable when listing sessions. type: string failure: $ref: '#/components/schemas/SessionFailure' description: >- Structured terminal failure. Omitted for healthy sessions and legacy rows. forked_at_event_id: description: >- Event in the parent session (UUID) this session was forked from, so the fork's starting context is identifiable. Set only on forks. type: string kind: description: >- What produced the session: api_call, chat, subagent (delegated by another session), or session_analyst (a platform-started read-only assistant that answers questions about another session tree). enum: - api_call - chat - rollout - subagent - benchmark - evaluation - reflection - session_analyst type: string last_activity_at: description: >- RFC 3339 timestamp of when the agent loop last made progress. Distinct from updated_at, which any metadata write touches. Absent for sessions that run no loop. format: date-time type: string metadata: additionalProperties: type: string description: >- Caller-defined string key/value pairs supplied when the session was started, e.g. ids from your own system. Immutable, present on root sessions only, and filterable with metadata=key:value or metadata_key=key on GET /managed-agents/v1/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters. type: object model_ref_id: description: >- Model reference the session's turns run on (UUID), resolved at start from the agent version or the start request. type: string model_snapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The resolved model reference and inference settings as they stood when the session started, frozen for the same reason as agent_snapshot. type: object organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string parent_session_id: description: >- Session that created this one (UUID) — the delegating session for a subagent, or the source session for a fork. Empty on a root session. type: string root_session_id: description: >- Root session of the multi-agent tree this session belongs to (UUID). Equal to session_id for a root session. type: string sandbox_instance_id: description: >- Provider-assigned id of the sandbox instance serving this session. Empty before provisioning finishes; historical self_hosted sessions may also have no instance id. type: string sandbox_provider: description: >- Sandbox runtime that provisioned this session's compute, from the supported sandbox providers list. type: string session_id: description: Identifier for this session (UUID). Server-assigned. type: string session_path: description: >- Position of this session within its tree, as a slash-delimited path of session ids. "/" for a root session. type: string source_refs: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Secondary provenance ids from the originating system beyond the primary external source, e.g. an imported rollout's problem, problem-version, and run ids. type: object status: $ref: '#/components/schemas/SessionStatus' description: >- Coarse session state shared with RL rollout imports: active, awaiting_human (for a rollout, carries no score), completed, failed, or cancelled. For where a running agent loop is, read execution_state instead. stop_reason: description: >- Why the loop is not running. Set whenever execution_state is idle or completed. sleeping means the agent chose to wait and the session resumes on the next message or at wake_at; awaiting_subagents means a coordinator is waiting on delegated work; out_of_credit means the billing tenant ran out of credit and the session paused before its next model request, and it continues on the next message once credit is added. type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string user_id: description: >- User the session was started on behalf of, resolved from the request scope. type: string vault_ids: description: >- Vaults (UUIDs) the session may draw credentials from. Combine with credential_refs to narrow the grant to specific credentials. items: type: string type: array wake_at: description: >- RFC 3339 timestamp at which a sleeping session wakes itself if nobody messages it first. Absent unless the agent scheduled a timed wait. format: date-time type: string required: - root_session_id - session_path - session_id - organization_id - kind - status - computer_use - credential_refs - credential_refs_configured - config - created_at - updated_at 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. ActiveHandoff: description: >- Public, credential-free state of a browser handoff that is awaiting a person, currently driven by one, or being resolved back to the agent. properties: access_expires_at: description: >- Latest time the current display access remains usable; never later than deadline_at. format: date-time type: string deadline_at: description: When the handoff automatically expires and the agent resumes. format: date-time type: string handoff_id: description: Stable identifier for this browser handoff. type: string reason: description: Why the agent asked a person to take over the shared browser. type: string requested_at: description: When the agent requested the handoff. format: date-time type: string state: description: >- Whether nobody has opened access yet, one person currently owns the display, or hand-back/deadline resolution is being delivered. enum: - awaiting_user - user_driving - resolved type: string wake_cause: description: >- Resolution cause once resolved: user_handed_back, deadline_elapsed, cancelled, or interrupted. type: string required: - handoff_id - reason - requested_at - deadline_at - state 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 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 SessionFailure: description: >- Structured, sanitized reason a session terminated abnormally. Present on a session only after a terminal failure; healthy and legacy sessions omit it. properties: at: description: Time the terminal failure was persisted. format: date-time type: string category: description: >- Who can act on this failure: transient (wait or retry), caller_error (change the request or configuration, retrying as-is will not help), or internal (report it). retryable=false with category=caller_error is a fixable mistake, not an outage. A retryable failure is never caller_error: if the platform will retry, changing the request is not the fix. enum: - transient - caller_error - internal type: string code: description: Stable machine-readable failure code. type: string message: description: >- Sanitized bounded operator-facing message; never contains raw provider response bodies or credentials. type: string phase: description: >- Lifecycle phase that failed, such as provisioning, setup, workflow, or model. type: string retryable: description: >- Whether the platform will retry, or a retry of the same request may succeed on its own. False does not mean permanently broken -- read category to tell a transient condition from a request the caller must change. type: boolean required: - phase - code - message - retryable - category - at type: object additionalProperties: false SessionStatus: description: Coarse session state shared by Managed Agents and imported RL rollouts. enum: - active - awaiting_human - completed - failed - cancelled type: string 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. ````