> ## 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. # Start a managed session > Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll managedAgentsGetSession or subscribe with managedAgentsStreamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Requires an Idempotency-Key header: the same key with the exact HTTP method, escaped path, raw query, and raw body bytes returns the original session; any difference is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning. Enabled provider_params.promptCacheTTL or provider_params.promptCacheSharedTTL settings with invalid values, an unsupported model, or shared retention shorter than history retention also return 400 before provisioning for the selected root agent version, including for previously stored agent versions. Roster agent cache settings are validated at delegation before creating each child session. A temporarily unavailable model reference or catalog dependency returns 503. An environment on managed compute whose setup script has no verified, current run returns 422 environment_not_verified before provisioning; run managedAgentsCreateEnvironmentSetupRun first. When the tenant is out of credit it returns 403 session_start_not_admitted with details.reason out_of_credit; add credits and retry. When the tenant is suspended it returns the same 403 with details.reason tenant_suspended. When the tenant already has as many sessions working at once as it may, it returns 429 tenant_concurrency_limit with details.limit; wait for a session to finish its turn or stop one, then retry. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/sessions 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/sessions: post: tags: - Sessions summary: Start a managed session description: >- Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll managedAgentsGetSession or subscribe with managedAgentsStreamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Requires an Idempotency-Key header: the same key with the exact HTTP method, escaped path, raw query, and raw body bytes returns the original session; any difference is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning. Enabled provider_params.promptCacheTTL or provider_params.promptCacheSharedTTL settings with invalid values, an unsupported model, or shared retention shorter than history retention also return 400 before provisioning for the selected root agent version, including for previously stored agent versions. Roster agent cache settings are validated at delegation before creating each child session. A temporarily unavailable model reference or catalog dependency returns 503. An environment on managed compute whose setup script has no verified, current run returns 422 environment_not_verified before provisioning; run managedAgentsCreateEnvironmentSetupRun first. When the tenant is out of credit it returns 403 session_start_not_admitted with details.reason out_of_credit; add credits and retry. When the tenant is suspended it returns the same 403 with details.reason tenant_suspended. When the tenant already has as many sessions working at once as it may, it returns 429 tenant_concurrency_limit with details.limit; wait for a session to finish its turn or stop one, then retry. operationId: managedAgentsStartSession parameters: - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key required: true schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/StartSessionRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/SessionCreatedResponse' description: >- Response body of POST /managed-agents/v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple Location: description: Canonical programmatic-host path to the accepted session. schema: type: string pattern: ^/managed-agents/v1/sessions/[^/?]+$ 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: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: '#/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: '#/components/schemas/ManagedAgentsApiErrorForbidden' session_start_not_admitted: >- #/components/schemas/ManagedAgentsApiErrorSessionStartNotAdmitted workspace_boundary_denied: >- #/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': headers: Retry-After: description: >- When present, delay in seconds or an HTTP-date after which the caller may retry; absence supplies no retry advice. schema: type: string style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Conflict. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress - $ref: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' discriminator: propertyName: code mapping: conflict: '#/components/schemas/ManagedAgentsApiErrorConflict' idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress revision_conflict: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' x-recursion-error-codes: - conflict - idempotency_conflict - idempotency_in_progress - revision_conflict '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' '422': description: Unprocessable Entity. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorEnvironmentNotVerified - $ref: >- #/components/schemas/ManagedAgentsApiErrorSandboxProviderDisabled discriminator: propertyName: code mapping: environment_not_verified: >- #/components/schemas/ManagedAgentsApiErrorEnvironmentNotVerified sandbox_provider_disabled: >- #/components/schemas/ManagedAgentsApiErrorSandboxProviderDisabled x-recursion-error-codes: - environment_not_verified - sandbox_provider_disabled 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: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded tenant_concurrency_limit: >- #/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/ManagedAgentsApiErrorFileStorageUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorMemoryPolicyReadUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable - $ref: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' - $ref: >- #/components/schemas/ManagedAgentsApiErrorRunnerImageResolutionFailed - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable discriminator: propertyName: code mapping: content_store_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured file_storage_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable memory_policy_read_unavailable: >- #/components/schemas/ManagedAgentsApiErrorMemoryPolicyReadUnavailable model_gateway_metadata_missing: >- #/components/schemas/ManagedAgentsApiErrorModelProviderMetadataMissing model_gateway_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnconfigured model_gateway_unreachable: >- #/components/schemas/ManagedAgentsApiErrorModelProviderUnreachable persistence_busy: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' runner_image_resolution_failed: >- #/components/schemas/ManagedAgentsApiErrorRunnerImageResolutionFailed service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable session_start_admission_unavailable: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable x-recursion-error-codes: - content_store_unconfigured - file_storage_unconfigured - idempotency_unavailable - managed_agents_unavailable - memory_policy_read_unavailable - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - persistence_busy - runner_image_resolution_failed - service_unavailable - 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: StartSessionRequest: description: >- Request body for starting a session: which agent to run, the environment to run it in, the vault grants it receives, and the opening message that gives it work. properties: agent_id: description: >- The agent to run, from POST /managed-agents/v1/agents or GET /managed-agents/v1/agents. Its current version is snapshotted into the session, so later edits to the agent do not affect this run. type: string credential_refs: description: >- Optional per-item allowlist inside vault_ids. The list is a whitelist across every granted vault, not a filter within one, so it must name every item the session should receive. Omit with explicit vault_ids to enable all items; [] alongside a non-empty vault_ids is rejected because it would enable none. Omit both fields to use the agent version's defaults. items: $ref: '#/components/schemas/VaultCredentialRef' type: array environment_id: description: >- The environment whose sandbox the session runs in, from POST /managed-agents/v1/environments or GET /managed-agents/v1/environments. type: string external_source_id: description: >- Stable identity inside the external system, e.g. a Slack thread key or a pull-request key. Set together with external_source_type. type: string external_source_type: description: >- Kind of external system this session correlates to, e.g. slack or github. Set together with external_source_id; sessions can then be filtered by both on GET /managed-agents/v1/sessions. type: string message: description: >- Opening user message for the session, and the context the agent works from. Kept in the session's system prompt for the whole run, so context compaction cannot summarize it away. Omit it or send an empty string for none; a message of only whitespace is refused with 400. type: string metadata: additionalProperties: type: string description: >- Caller-defined string key/value pairs stored on the session, e.g. ids that map it back to your own system. Write-once: they cannot be changed after start. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters without control characters. Returned as metadata on GET /managed-agents/v1/sessions and filterable with metadata=key:value (repeatable, AND) or metadata_key=key. maxProperties: 32 type: object project_id: description: >- Billing project this session is attributed to. Required when the agent runs on a model family that serves only named projects; refused with 400 for an organization whose model list has no such family. type: string referenced_session_ids: description: >- Prior readable sessions whose trees this session may use as context. Each id must be in the same organization and readable by the caller; otherwise the entire request returns 404. Session-analyst conversations cannot be referenced. items: type: string maxItems: 10 type: array resources: description: >- Files to mount read-only into the session's sandbox, under its files directory, before the first turn. Each attaches the file's content as it is now. All-or-nothing: one unknown or out-of-scope file_id refuses the whole request with 404 and creates nothing. Requires an environment with a sandbox. items: $ref: '#/components/schemas/SessionResourceRequest' maxItems: 500 type: array team: $ref: '#/components/schemas/TeamRequest' description: >- How this session's tree may work as a team. Every tree has a shared task board: under mode auto (the default) the agent becomes a team the moment it posts its first task, recruiting copies of itself one per claimable task, which share its sandbox, claim work from the board, and are woken by its transitions; mode on makes it a team from turn one; mode off withholds the board. Overrides the agent's multiagent.team mode for this session; an agent with no roster runs under default limits. Governance (thread and cost caps) is the agent's and cannot be widened here. vault_ids: description: >- Vault grants for this session. Omit to use the agent version's default_vault_ids; send [] to disable all defaults. items: type: string type: array required: - agent_id type: object additionalProperties: false SessionCreatedResponse: description: >- Response body of POST /managed-agents/v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution. properties: session_id: description: >- Identifier for this session (UUID). Server-assigned. Derived deterministically from the durable idempotency receipt for a keyed request, so an exact retry returns the same id rather than starting a second session. type: string status_path: type: string pattern: ^/managed-agents/v1/sessions/[^/?]+$ description: Canonical programmatic-host path to the accepted session. required: - session_id - status_path 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. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. 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. ManagedAgentsApiErrorEnvironmentNotVerified: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - environment_not_verified 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. ManagedAgentsApiErrorSandboxProviderDisabled: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - sandbox_provider_disabled 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. ManagedAgentsApiErrorFileStorageUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - file_storage_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. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorMemoryPolicyReadUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - memory_policy_read_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. ManagedAgentsApiErrorRunnerImageResolutionFailed: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - runner_image_resolution_failed 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. 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. 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 SessionResourceRequest: description: One file to attach to a session. properties: file_id: description: >- The file to mount. Must belong to the caller's organization and not have expired. format: uuid type: string mount_path: description: >- The same place named absolutely, with the session's files directory as its root: /data/input.csv lands at data/input.csv, as does the directory's own absolute path copied from a session's resource list, and the /mnt/session/uploads/ prefix is accepted as an alias for the directory. Any other absolute root is likewise a path beneath the directory, never a mount elsewhere. Paths take the same shape rules as relative_path (no . or .. segments, no control characters, at most 255 characters); the filename's reserved-character rule does not apply to paths. Set this or relative_path; both are accepted only when they agree. type: string relative_path: description: >- Where the file lands relative to the session's files directory, e.g. data/input.csv. Defaults to the file's own name. Must be unique within the session and may not contain . or .. segments. type: string type: description: Always file. enum: - file type: string required: - type - file_id type: object additionalProperties: false TeamRequest: description: >- Per-session override of the agent's team setting: whether the tree may become a team. Omit the mode to keep the agent's setting. The seats a team may fill are the roster's limits.max_concurrent_threads; recruits are sized to the claimable work under that cap, and teammates may always message each other directly. properties: mode: description: >- auto (default): the board tools are offered and the tree becomes a team when the agent posts its first task. on: a team from turn one, briefed as one before it has posted anything. off: no board; the agent delegates and waits as a plain coordinator. Omit to keep the agent's setting. enum: - auto - 'on' - 'off' type: string 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. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````