> ## 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. # Append user/system events to a session > Accepts ordered user and system messages and returns how many were accepted. A running session is woken so the agent sees them, and a finished session resumes to act on them; delivery_state reports how they were delivered. Events are appended in the order given. An omitted or empty events array yields exactly one user turn built from message; the request fails with 400 only when every entry sent was dropped, leaving nothing to append. A top-level image or document block may name a file with source {type: file, file_id}: an unknown, expired, or foreign file answers 404 on that block's source.file_id, a file the block cannot carry (a file whose bytes are not an image on an image block, a binary on a document block, a document over 512 KiB, more than 1 MiB of documents in one event, more than 100 such blocks, or more than 32 MiB of catalog bytes in one request) answers 400 there, and nothing is appended to the transcript; copies of files resolved before the refusal are kept with the session and removed once nothing references them. Without file storage such a block answers 503 file_storage_unconfigured. An optional Idempotency-Key makes a retry after an ambiguous transport failure replay the first response instead of appending the events again. When the tenant is out of credit, a message returns 403 session_start_not_admitted with details.reason out_of_credit and nothing is appended; add credits and send it again. A suspended tenant gets the same 403 with details.reason tenant_suspended. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/sessions/{sessionId}/events 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/{sessionId}/events: post: tags: - Sessions summary: Append user/system events to a session description: >- Accepts ordered user and system messages and returns how many were accepted. A running session is woken so the agent sees them, and a finished session resumes to act on them; delivery_state reports how they were delivered. Events are appended in the order given. An omitted or empty events array yields exactly one user turn built from message; the request fails with 400 only when every entry sent was dropped, leaving nothing to append. A top-level image or document block may name a file with source {type: file, file_id}: an unknown, expired, or foreign file answers 404 on that block's source.file_id, a file the block cannot carry (a file whose bytes are not an image on an image block, a binary on a document block, a document over 512 KiB, more than 1 MiB of documents in one event, more than 100 such blocks, or more than 32 MiB of catalog bytes in one request) answers 400 there, and nothing is appended to the transcript; copies of files resolved before the refusal are kept with the session and removed once nothing references them. Without file storage such a block answers 503 file_storage_unconfigured. An optional Idempotency-Key makes a retry after an ambiguous transport failure replay the first response instead of appending the events again. When the tenant is out of credit, a message returns 403 session_start_not_admitted with details.reason out_of_credit and nothing is appended; add credits and send it again. A suspended tenant gets the same 403 with details.reason tenant_suspended. operationId: managedAgentsSendSessionEvents parameters: - description: >- Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions. in: path name: sessionId required: true schema: description: >- Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions. 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 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/SessionEventSendRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EventsAcceptedResponse' description: >- Shared response body of POST /managed-agents/v1/sessions/{sessionId}/events and POST /managed-agents/v1/sessions/{sessionId}/interrupt-and-send. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt-and-send reports 2 for its single instruction: the stop and the message that follows it. 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: 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 discriminator: propertyName: code mapping: conflict: '#/components/schemas/ManagedAgentsApiErrorConflict' idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress x-recursion-error-codes: - conflict - idempotency_conflict - idempotency_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: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffAccessUnsupported - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffRequiresRetest discriminator: propertyName: code mapping: handoff_access_unsupported: >- #/components/schemas/ManagedAgentsApiErrorHandoffAccessUnsupported handoff_requires_retest: >- #/components/schemas/ManagedAgentsApiErrorHandoffRequiresRetest x-recursion-error-codes: - handoff_access_unsupported - handoff_requires_retest headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffCaptureUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffRevokeUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffRevokeUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorHandoffSignalUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable discriminator: propertyName: code mapping: content_store_unavailable: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable content_store_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured file_storage_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured handoff_capture_unavailable: >- #/components/schemas/ManagedAgentsApiErrorHandoffCaptureUnavailable handoff_revoke_unavailable: >- #/components/schemas/ManagedAgentsApiErrorHandoffRevokeUnavailable handoff_revoke_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorHandoffRevokeUnconfigured handoff_signal_unavailable: >- #/components/schemas/ManagedAgentsApiErrorHandoffSignalUnavailable idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable persistence_busy: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable session_start_admission_unavailable: >- #/components/schemas/ManagedAgentsApiErrorSessionStartAdmissionUnavailable x-recursion-error-codes: - content_store_unavailable - content_store_unconfigured - file_storage_unconfigured - handoff_capture_unavailable - handoff_revoke_unavailable - handoff_revoke_unconfigured - handoff_signal_unavailable - idempotency_unavailable - managed_agents_unavailable - persistence_busy - 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: SessionEventSendRequest: description: >- Request body of POST /managed-agents/v1/sessions/{sessionId}/events. It has two mutually exclusive forms and events wins: send message for the common case of one plain-text user turn, or send events as ordered typed turns with provider-shaped content. An empty events array yields exactly one user turn built from message, which must not be empty or only whitespace. The handoff_resolved control form rejects all message and referenced-session fields. The response acknowledges durable acceptance of the turn, not the agent's reply. properties: actor: description: Who the turn is attributed to. Defaults to human:api when omitted. type: string events: description: >- Typed events to append instead of message. When present, message and the top-level actor are ignored. items: $ref: '#/components/schemas/ManagedEventSendParams' type: - array - 'null' message: description: >- Plain-text message to append as a single user turn. Used only when events is empty, and then required: a message that is empty or only whitespace is refused with 400. type: string referenced_session_ids: description: >- Prior sessions this session may read from this turn on, by session id, added to any it already has. Each id is authorized under your own scope and grants read access to the whole tree containing it; one you cannot read refuses the whole request with 404 and delivers no message. The grant is recorded before the message, so the turn it starts is the first one that can use it. items: type: string maxItems: 10 type: array type: object additionalProperties: false EventsAcceptedResponse: description: >- Shared response body of POST /managed-agents/v1/sessions/{sessionId}/events and POST /managed-agents/v1/sessions/{sessionId}/interrupt-and-send. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt-and-send reports 2 for its single instruction: the stop and the message that follows it. properties: delivery_state: description: >- How the accepted events reached a reader. queued: the agent was mid-turn, so the input is waiting outside the transcript and the next turn boundary will read it; interrupt to bring that forward. signaled: the running session was woken and will act on them. resumed: the session had already finished, so it resumed to act on them. stored: appended to the timeline with nothing running to act on them yet. enum: - stored - signaled - resumed - queued type: string events_accepted: description: >- How many canonical events were written or queued. This counts the inputs actually derived from the body, not its length: a plain message body yields 1, and a typed user.message with no content is dropped, so this can be lower than the events array sent. type: integer minimum: -9007199254740991 maximum: 9007199254740991 ok: description: >- Always true. Every event in the request was durably accepted; any partial or total failure is an HTTP error instead, so this field never reports false. type: boolean required: - ok - delivery_state - events_accepted 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. 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. ManagedAgentsApiErrorHandoffAccessUnsupported: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_access_unsupported 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. ManagedAgentsApiErrorHandoffRequiresRetest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_requires_retest message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorContentStoreUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_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. 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. ManagedAgentsApiErrorHandoffCaptureUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_capture_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. ManagedAgentsApiErrorHandoffRevokeUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_revoke_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. ManagedAgentsApiErrorHandoffRevokeUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_revoke_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. ManagedAgentsApiErrorHandoffSignalUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - handoff_signal_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. 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. 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. 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. ManagedEventSendParams: description: >- One typed event in the events array of a POST /managed-agents/v1/sessions/{sessionId}/events body. A user.message carrying neither content nor text is dropped silently rather than rejected, so compare events_accepted in the response against how many entries were sent. An unrecognised type, and content that is sent but carries nothing -- only whitespace text, or no blocks on a system.message -- are refused with 400 on that entry. handoff_resolved is a strict control event: it must be the only entry and accepts only type, handoff_id, and note. If every entry was dropped, leaving nothing to accept, the request also fails with 400. properties: actor: description: Who this event is attributed to. Defaults to human:api when omitted. type: string content: description: >- Provider-shaped content blocks, passed through verbatim, except that a top-level image or document block may name a file from the organization's catalog with source {type: file, file_id} instead of carrying bytes: the file is read when the message is accepted, an image is copied into the session and the block keeps the source beside the copy's uri, and a text document is inlined as a text block wrapped with its source, name, title, and context. The send route's description carries the limits on such blocks and what they may bring in. Takes precedence over text. items: $ref: '#/components/schemas/ContentBlockRequest' type: - array - 'null' handoff_id: description: >- Stable id from session.active_handoff. Required for handoff_resolved and ignored for message events. type: string note: description: >- Optional note telling the agent what the user did before handing the browser back. Used only for handoff_resolved. maxLength: 2000 type: string text: description: >- Convenience shorthand for a single text content block. Ignored when content is set. type: string type: description: >- Event type. Defaults to user.message when omitted. handoff_resolved is the dedicated control event for handing the shared browser back; it must be the only event in the request. Any other value is rejected with 400 on that entry and nothing is appended. Interrupts use the permission-isolated interrupt endpoints. enum: - user.message - system.message - handoff_resolved 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. ContentBlockRequest: description: >- One caller-supplied message content block. Nested content and summary blocks cannot carry file sources or document blocks. properties: byte_size: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content: items: $ref: '#/components/schemas/NestedContentBlockRequest' type: array context: type: string data: type: string encrypted_content: type: string height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 id: type: string input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object is_error: type: boolean media_type: type: string name: type: string omitted_bytes: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 payload: $ref: '#/components/schemas/PlatformSafeJsonValue' provider: type: string provider_payload: $ref: '#/components/schemas/PlatformSafeJsonValue' redacted: type: boolean semantic_hint: type: string sha256: type: string signature: type: string source: $ref: '#/components/schemas/ContentBlockSource' summary: items: $ref: '#/components/schemas/NestedContentBlockRequest' type: array text: type: string title: type: string tool_use_id: type: string type: type: string uri: type: string width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object additionalProperties: false allOf: - if: properties: type: const: document required: - type then: required: - source - if: required: - source then: properties: type: enum: - text - image - document required: - type 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 NestedContentBlockRequest: description: >- One nested caller-supplied message content block. File sources, document blocks, and read-time signed URLs are not accepted when nested. properties: byte_size: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content: items: $ref: '#/components/schemas/NestedContentBlockRequest' type: array context: type: string data: type: string encrypted_content: type: string height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 id: type: string input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object is_error: type: boolean media_type: type: string name: type: string omitted_bytes: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 payload: $ref: '#/components/schemas/PlatformSafeJsonValue' provider: type: string provider_payload: $ref: '#/components/schemas/PlatformSafeJsonValue' redacted: type: boolean semantic_hint: type: string sha256: type: string signature: type: string summary: items: $ref: '#/components/schemas/NestedContentBlockRequest' type: array text: type: string title: type: string tool_use_id: type: string type: type: string not: const: document description: >- Nested block type. Document blocks are only accepted at the message root. uri: type: string width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object additionalProperties: false ContentBlockSource: description: >- Where a user-sent image or document block takes its bytes from when the caller names a file instead of carrying them: a file from the organization's catalog, read and copied into the session when the message is accepted, so the block the transcript keeps names both the source and the copy. properties: file_id: type: string minLength: 1 description: Nonempty id of an unexpired file in the caller's organization. type: type: string const: file description: Always file. required: - type - file_id type: object additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````