> ## 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. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/sessions/{session_id}/events openapi: 3.1.0 info: title: Managed Agents API version: 0.13.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/{session_id}/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. operationId: managedAgentsSendSessionEvents parameters: - description: Session id (UUID) as returned by startSession or listSessions. in: path name: session_id required: true schema: description: Session id (UUID) as returned by startSession or listSessions. format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsSessionEventSendRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsEventsAcceptedResponse' description: >- Shared response body of POST /v1/sessions/{session_id}/events and POST /v1/sessions/{session_id}/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. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '409': description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '422': description: The request is well formed but failed semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '429': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '500': description: An unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsSessionEventSendRequest: description: >- Request body of POST /v1/sessions/{session_id}/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 always yields exactly one user turn built from message, even when message is empty. 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/ManagedAgentsManagedEventSendParams' type: - array - 'null' message: description: >- Plain-text message to append as a single user turn. Used only when events is empty. 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 example: actor: human:api events: - actor: human:api content: - byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 handoff_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d note: example text: example type: user.message message: example referenced_session_ids: - example ManagedAgentsEventsAcceptedResponse: description: >- Shared response body of POST /v1/sessions/{session_id}/events and POST /v1/sessions/{session_id}/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 event with an unrecognised type or no content is dropped, so this can be lower than the events array sent. type: integer 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 example: delivery_state: stored events_accepted: 1 ok: true ManagedAgentsApiError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - analytics - analytics_not_ready - artifact_fetch_unavailable - artifact_generation_mismatch - artifact_hash_mismatch - artifact_invalid_events - artifact_invalid_json - artifact_not_allowlisted - artifact_size_mismatch - atlassian_rate_limited - atlassian_unavailable - atomic_ingest_timeout - auth_unavailable - automation_event_source_invalid - automation_memory_unavailable - automation_reference_invalid - automation_runs_unconfigured - automations_unconfigured - bad_gateway - built_in_catalog_unavailable - built_in_integrations_disabled - built_in_integrations_unconfigured - compute_offerings_unavailable - conflict - content_store_request_canceled - content_store_unavailable - content_store_upload_timeout - credential_encryption_unconfigured - delegate_preparation_failed - entity_family_not_permitted - environment_not_verified - evaluation_cancellation_pending - evaluation_deletion_pending - event_admission_unavailable - event_ingress_unavailable - event_source_verification_credential_invalid - event_sources_unconfigured - execution_unconfigured - file_quota_exceeded - file_storage_unconfigured - forbidden - gateway_timeout - gestalt_unconfigured - github_rate_limited - github_unavailable - handoff_access_invalid - handoff_access_unavailable - handoff_access_unsupported - handoff_capture_unavailable - handoff_requires_retest - handoff_revoke_unavailable - handoff_signal_unavailable - idempotency_conflict - idempotency_in_progress - idempotency_unavailable - ingest_policy_changed - ingest_policy_not_found - ingest_policy_revoked - integrations_unconfigured - internal_error - invalid_json - invalid_pull_request_review_result - invalid_request - invalid_scope - invariant_violation - launchdarkly_rate_limited - launchdarkly_unavailable - live_fleet_unconfigured - managed_agents_unavailable - merge_key_rejected - merge_link_unavailable - merge_rate_limited - merge_unavailable - missing_dependency - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - mutation_transaction_budget_exceeded - not_found - page_token_expired - payload_too_large - persistence_busy - precondition_failed - precondition_required - provider_registration_unsupported - provider_selection_unsupported - rate_limit_exceeded - rate_limited - repository_automation_unconfigured - request_too_large - reserved_source_type - revision_conflict - run_log_store_unavailable - runner_image_resolution_failed - sandbox_provider_disabled - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_unavailable - session_start_not_admitted - setup_fallback_environment_unsafe - setup_run_finished - setup_run_in_progress - setup_run_limit - setup_run_not_started - setup_runs_unavailable - skill_storage_unconfigured - slack_channels_rejected - slack_channels_unavailable - slack_channels_unconfigured - slack_connection_malformed - slack_event_intake_unavailable - slack_installation_mismatch - slack_missing_scope - slack_rate_limited - slack_reapproval_required - source_ownership_mismatch - source_revision_conflict - spanner_unavailable - streaming_unsupported - submission_transaction_budget_exceeded - task_version_number_conflict - team_board_unconfigured - too_many_streams - unauthorized - unsupported_media_type - vault_creation_retired - version_content_conflict - webhook_delivery_too_large - workspace_boundary_denied message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsManagedEventSendParams: description: >- One typed event in the events array of a POST /v1/sessions/{session_id}/events body. It is lenient for messages: an unrecognised type, and a user.message carrying neither content nor text, are dropped silently rather than rejected, so compare events_accepted in the response against how many entries were sent. handoff_resolved is a strict control event: it must be the only entry and accepts only type, handoff_id, and note. The request fails with 400 only if every entry was dropped, leaving nothing to accept. 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/ManagedAgentsContentBlockRequest' 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. Other unrecognised values are silently ignored. Interrupts use the permission-isolated interrupt endpoints. enum: - user.message - system.message - handoff_resolved type: string type: object example: actor: human:api content: - byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 handoff_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d note: example text: example type: user.message ManagedAgentsContentBlockRequest: description: >- One block of message content: text, image, tool_use, tool_result, thinking, or a provider passthrough. The type field says which fields apply, and provider-native payloads are carried through verbatim. properties: byte_size: description: Decoded image byte size. format: int64 type: integer content: description: >- Nested blocks carrying a tool_result payload, so a tool can return both text and images. items: $ref: '#/components/schemas/ManagedAgentsContentBlockRequest' type: array context: description: >- A document block's context: what the model should know about the document before reading it, disclosed as its first paragraph. type: string data: description: >- Base64 image bytes. Omitted from default reads and present only for legacy storage or explicit hydrate=images responses. type: string encrypted_content: description: >- Sealed reasoning payload for providers that return reasoning encrypted. Opaque to clients; replay it verbatim. type: string height: description: Validated image height in pixels. type: integer id: description: >- Provider-assigned id of a tool_use block. Echo it back as tool_use_id on the matching tool_result. type: string input: additionalProperties: {} description: >- Tool arguments the model produced for a tool_use block, matching that tool's input schema. type: object is_error: description: >- True when a tool_result reports that the tool call failed; the nested content then carries the error detail. type: boolean media_type: description: >- Declared media type; inline computer-use images allow image/jpeg, image/png, and image/webp. type: string name: description: Name of the tool the model is invoking, on a tool_use block. type: string omitted_bytes: description: Original byte count reported by a redacted image placeholder. format: int64 type: integer payload: description: >- Provider-native block body, stored verbatim for block types this schema does not model. Passed through unchanged. provider: description: >- Provider that emitted a passthrough block, e.g. anthropic or openai, telling readers how to interpret payload. type: string provider_payload: description: >- Original provider block exactly as received, kept alongside the normalized fields for lossless replay. redacted: description: >- True when the block's content was withheld (redacted thinking, or an image dropped by redaction); the remaining fields describe what was removed. type: boolean semantic_hint: description: >- Coarse hint about what an unmodeled provider block represents, so a reader can render it without provider-specific logic. type: string sha256: description: Lowercase SHA-256 digest of decoded image bytes. type: string signature: description: >- Provider-issued signature over a thinking block, or the thought signature a Gemini tool_use block was issued with, required for the provider to accept that block on a later turn. Opaque; replay it verbatim. type: string source: $ref: '#/components/schemas/ManagedAgentsContentBlockSource' description: >- Where a user-sent image or document block's bytes came from when they were named rather than sent inline: {type: "file", file_id}. Kept on the stored block as provenance after the bytes were copied into the session; an image block then also carries the session's own uri. summary: description: >- Readable summary blocks a provider returns alongside sealed or long-form reasoning. items: $ref: '#/components/schemas/ManagedAgentsContentBlockRequest' type: array text: description: Text of a text block, or the reasoning text of a thinking block. type: string title: description: >- A document block's title, disclosed to the model beside the document. type: string tool_use_id: description: Id of the tool_use block that this tool_result answers. type: string type: description: >- Block discriminator: text, image, document (a user-sent block naming a file by id, inlined as text when the message is accepted), tool_use, tool_result, thinking, redacted_thinking, or a provider passthrough type. Which of the other fields apply depends on this value. type: string uri: description: >- Private typed content reference. Fetch it through getSessionImage; clients cannot read this URI directly. type: string url: description: >- Short-lived HTTPS URL for the image bytes. Present only when the read asked for image_urls=signed and the deployment has signing configured. Never stored; fetch a fresh read after url_expires_at. type: string url_expires_at: description: When url stops working. Absent whenever url is. format: date-time type: - 'null' - string width: description: Validated image width in pixels. type: integer type: object example: byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 ManagedAgentsContentBlockSource: 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: description: >- The file whose bytes the block carries, from the caller's organization, unexpired. type: string type: description: Always file. enum: - file type: string required: - type - file_id type: object example: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````