> ## 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. # Run and verify the environment's setup script > Requires Idempotency-Key because this operation provisions billable compute. Provisions fresh compute for the environment, runs its setup script exactly as a session would (same image, resources, and variables; no session credentials), records every line of output, profiles the compute, releases it, and writes the verdict to the environment's setup_verification. Returns 202 with the queued run; poll managedAgentsGetEnvironmentSetupRun with wait_seconds until status is succeeded, failed, or cancelled. On failure read hint, failed_line, and stderr_tail first, then the log. One run at a time per environment: a second request while one is in flight is a 409 naming the run to poll. Repeating the exact request with the same Idempotency-Key replays the original 202 response without starting another run. 400 when the environment has no setup script. This spends compute. When the tenant is out of credit, returns 403 setup_run_not_admitted with details.reason out_of_credit; buy credits and retry. A suspended tenant gets the same 403 with details.reason tenant_suspended. An unavailable credit check returns 503 setup_run_admission_unavailable without recording a run. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/environments/{environmentId}/setup-runs 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/environments/{environmentId}/setup-runs: post: tags: - Environments summary: Run and verify the environment's setup script description: >- Requires Idempotency-Key because this operation provisions billable compute. Provisions fresh compute for the environment, runs its setup script exactly as a session would (same image, resources, and variables; no session credentials), records every line of output, profiles the compute, releases it, and writes the verdict to the environment's setup_verification. Returns 202 with the queued run; poll managedAgentsGetEnvironmentSetupRun with wait_seconds until status is succeeded, failed, or cancelled. On failure read hint, failed_line, and stderr_tail first, then the log. One run at a time per environment: a second request while one is in flight is a 409 naming the run to poll. Repeating the exact request with the same Idempotency-Key replays the original 202 response without starting another run. 400 when the environment has no setup script. This spends compute. When the tenant is out of credit, returns 403 setup_run_not_admitted with details.reason out_of_credit; buy credits and retry. A suspended tenant gets the same 403 with details.reason tenant_suspended. An unavailable credit check returns 503 setup_run_admission_unavailable without recording a run. operationId: managedAgentsCreateEnvironmentSetupRun parameters: - description: >- Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments. in: path name: environmentId required: true schema: description: >- Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments. format: uuid type: string - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key required: true schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '202': content: application/json: schema: $ref: '#/components/schemas/EnvironmentSetupRun' description: >- One execution of an environment's setup script on fresh compute: provision, GPU check, script, profile, image capture, cleanup. Read status until terminal, then hint, failed_line, and stderr_tail; the full log is a separate call. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' - $ref: >- #/components/schemas/ManagedAgentsApiErrorSetupRunNotAdmitted discriminator: propertyName: code mapping: forbidden: '#/components/schemas/ManagedAgentsApiErrorForbidden' setup_run_not_admitted: >- #/components/schemas/ManagedAgentsApiErrorSetupRunNotAdmitted x-recursion-error-codes: - forbidden - setup_run_not_admitted 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/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress - $ref: >- #/components/schemas/ManagedAgentsApiErrorSetupRunInProgress discriminator: propertyName: code mapping: idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress setup_run_in_progress: >- #/components/schemas/ManagedAgentsApiErrorSetupRunInProgress x-recursion-error-codes: - idempotency_conflict - idempotency_in_progress - setup_run_in_progress '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '422': description: Unprocessable Entity. content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsApiErrorSandboxProviderDisabled x-recursion-error-codes: - 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/ManagedAgentsApiErrorSetupRunLimit' discriminator: propertyName: code mapping: rate_limit_exceeded: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded setup_run_limit: '#/components/schemas/ManagedAgentsApiErrorSetupRunLimit' x-recursion-error-codes: - rate_limit_exceeded - setup_run_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/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSetupRunAdmissionUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSetupRunNotStarted discriminator: propertyName: code mapping: idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable setup_run_admission_unavailable: >- #/components/schemas/ManagedAgentsApiErrorSetupRunAdmissionUnavailable setup_run_not_started: >- #/components/schemas/ManagedAgentsApiErrorSetupRunNotStarted x-recursion-error-codes: - idempotency_unavailable - managed_agents_unavailable - service_unavailable - setup_run_admission_unavailable - setup_run_not_started 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: EnvironmentSetupRun: description: >- One execution of an environment's setup script on fresh compute: provision, GPU check, script, profile, image capture, cleanup. Read status until terminal, then hint, failed_line, and stderr_tail; the full log is a separate call. properties: compute_id: description: Provider id of the compute the run used. Released when the run ends. type: string compute_profile: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- What the compute turned out to be: vCPUs, memory, GPUs, Docker state, image tools. Recorded after setup passed. type: object created_at: description: When the run was requested. format: date-time type: string duration_ms: description: Wall-clock duration in milliseconds, provisioning included. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 environment_id: description: Environment whose setup ran. type: string exit_code: description: >- Exit code of the setup script when it ran. 124 means the timeout elapsed. type: integer minimum: -9007199254740991 maximum: 9007199254740991 failed_command: description: The failing line's command as written, unexpanded. type: string failed_line: description: >- 1-based line in the setup script whose command exited non-zero. 0 when unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 failure_code: description: >- Machine-readable failure class when the run did not succeed: environment_setup_failed, sandbox_capacity_unavailable, sandbox_gpu_not_ready, sandbox_provision_timeout, and so on. Same vocabulary as session failures. type: string fingerprint: description: Hash of the environment configuration the run executed. type: string finished_at: description: When the run reached a terminal status. format: date-time type: string gpu_readiness: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: GPU readiness report for accelerator environments. type: object hint: description: Likely fix when the failure cause is recognised. type: string hint_code: description: Stable identifier of the recognised failure cause. type: string image: description: Runner image the compute booted. type: string imageCapture: $ref: '#/components/schemas/EnvironmentSetupImageCapture' description: Capture failure recorded without changing the setup script verdict. imageId: description: Agent Service image id being captured. type: string kind: description: >- manual (requested through the API), runner_refresh (automatically captures an image for the current runner), or session (legacy in-session setup). type: string log_bytes: description: Bytes of log persisted for the run. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 log_lines: description: >- Lines of log persisted for the run. The last line's seq equals this; pass it as after to tail. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 log_truncated: description: >- True when the script produced more output than the run keeps (4 MiB); the head and the stderr tail are retained. type: boolean message: description: One-sentence description of the outcome. type: string next_action: $ref: '#/components/schemas/NextAction' description: >- The call that acts on this result: re-run setup after fixing the script, or fetch the log. organization_id: description: Organization that owns the environment. type: string phase: description: >- Current or final phase: provision, gpu_check, setup, profile, commit, cleanup. type: string providerRunId: description: Durable Agent Service run id executing the setup script. type: string requested_by_user_id: description: User who requested a manual run. type: string session_id: description: Session the run provisioned, for kind session. type: string setup_run_id: description: Server-assigned id of the run. type: string setupImage: $ref: '#/components/schemas/EnvironmentSetupImage' description: Immutable image published by this run when capture succeeded. started_at: description: When provisioning began. format: date-time type: string status: description: >- queued, provisioning, running, succeeded, failed, or cancelled. Poll until one of the last three; managedAgentsGetEnvironmentSetupRun accepts wait_seconds to do that server-side. type: string stderr_tail: description: Last lines of stderr, redacted and bounded to 2 KiB. type: string required: - organization_id - environment_id - setup_run_id - kind - status - created_at type: object additionalProperties: false 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. ManagedAgentsApiErrorSetupRunNotAdmitted: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_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. 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. 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. ManagedAgentsApiErrorSetupRunInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_in_progress message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. 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. ManagedAgentsApiErrorSetupRunLimit: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_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. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorSetupRunAdmissionUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_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. ManagedAgentsApiErrorSetupRunNotStarted: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_not_started 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. 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 EnvironmentSetupImageCapture: description: Why a verified setup run published no new reusable image. properties: at: description: When the capture failure was recorded. format: date-time type: string message: description: Sanitized bounded explanation. type: string reason: description: Stable Agent Service capture failure reason. type: string setupRunId: description: Setup run whose capture failed. type: string status: description: Always failed; successful capture is represented by image. enum: - failed type: string required: - status - setupRunId - at type: object additionalProperties: false NextAction: description: >- The literal next API call to make. Included on errors and results whose resolution is one known call, so a caller need not infer it. properties: method: description: HTTP method of that call. type: string operation_id: type: string enum: - managedAgentsGetEnvironmentSetupRunLog - managedAgentsCreateEnvironmentSetupRun - managedAgentsStartSession - managedAgentsGetEnvironmentSetupRun description: Public Recursion operation id of the call to make next. path: type: string pattern: ^/managed-agents/v1(?:/|$) description: >- Canonical programmatic-host path with path parameters already filled in. required: - operation_id - method - path type: object additionalProperties: false EnvironmentSetupImage: description: >- An immutable setup image published after a manual or automatic setup run passes. Identity includes the environment fingerprint, configured runner, observed base digest, and capture generation. properties: baseImageDigest: description: Immutable base image reference observed by Agent Service. type: string capturedAt: description: When Agent Service reported the image ready. format: date-time type: string computeId: description: Agent Service compute whose filesystem was captured. type: string fingerprint: description: Environment configuration fingerprint this image was produced for. type: string generation: description: Capture and boot contract generation. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 image: description: Immutable digest-pinned image reference. type: string imageId: description: Agent Service image id. type: string runnerImage: description: Exact configured runner reference selected for the captured compute. type: string setupRunId: description: Manual or automatic setup run that produced this image. type: string sizeBytes: description: Captured filesystem layer size. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 usable: description: >- Registry-free read-time projection for the active verified environment and configured runner. A moving tag may have changed since this projection; session admission resolves its exact digest before choosing the captured image or a runner refresh. type: boolean warmup: description: >- Agent Service warmup state: pulling, verifying, ready, failed, or unavailable. type: string warmupMessage: description: Bounded Agent Service explanation of the warmup state. type: string required: - imageId - computeId - setupRunId - image - baseImageDigest - fingerprint - runnerImage - generation - sizeBytes - capturedAt 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. 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. ````