> ## 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. # Upload a file > Stores a file the organization can attach to any number of sessions. Attaching one mounts it read-only into the session's sandbox under its files directory, and the agent knows where to find it. Send the bytes as the file part of a multipart/form-data body; the part's filename and Content-Type become the file's name and media type. The file part may contain at most 30 MiB, and the complete multipart request may use at most 128 KiB more for framing and form fields. Larger files are not supported by this Platform V1 operation. The bytes are served back through GET /managed-agents/v1/files/{fileId}/content to the same organization. A request over the transport limit answers 413 with code payload_too_large. An upload that would carry the organization's live files past its storage quota answers 413 with code file_quota_exceeded and reports the quota, bytes in use, and incoming size in details. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/files 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/files: post: tags: - Files summary: Upload a file description: >- Stores a file the organization can attach to any number of sessions. Attaching one mounts it read-only into the session's sandbox under its files directory, and the agent knows where to find it. Send the bytes as the file part of a multipart/form-data body; the part's filename and Content-Type become the file's name and media type. The file part may contain at most 30 MiB, and the complete multipart request may use at most 128 KiB more for framing and form fields. Larger files are not supported by this Platform V1 operation. The bytes are served back through GET /managed-agents/v1/files/{fileId}/content to the same organization. A request over the transport limit answers 413 with code payload_too_large. An upload that would carry the organization's live files past its storage quota answers 413 with code file_quota_exceeded and reports the quota, bytes in use, and incoming size in details. operationId: managedAgentsUploadFile parameters: - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FormDataFileUploadRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/File' description: >- A file object: bytes uploaded once and attachable to any number of sessions as a resource, or bytes a session produced. Attaching a file mounts it read-only into the session's sandbox at a path the session is told about. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: '#/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: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden 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' '413': description: Payload Too Large. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorFileQuotaExceeded - $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' discriminator: propertyName: code mapping: file_quota_exceeded: >- #/components/schemas/ManagedAgentsApiErrorFileQuotaExceeded payload_too_large: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - file_quota_exceeded - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When 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/ManagedAgentsApiErrorFileStorageUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: file_storage_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - file_storage_unconfigured - managed_agents_unavailable - service_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: FormDataFileUploadRequest: description: >- Multipart body for uploading a file. Send the bytes as the file part; the part's filename and Content-Type become the file's name and media type. properties: expires_in_seconds: description: >- How long the file stays attachable and its content served, from 3600 (an hour) to 7776000 (ninety days); its metadata stays readable, with expires_at in the past, for a grace after that. Omit for a file that does not expire. Set once: a file's expiry cannot be changed. format: int64 type: integer x-recursion-omission: strategy: absent minimum: -9007199254740991 maximum: 9007199254740991 file: contentMediaType: application/octet-stream description: >- The file's bytes. Its part filename is the name the file is stored and mounted under; its part Content-Type is recorded as the media type. The file part may contain at most 30 MiB; larger files are not supported by this Platform V1 operation. format: binary type: string metadata: description: >- Caller-owned key/value data as a JSON object, since a form part cannot carry structure. Rejected rather than dropped when it does not parse. type: string x-recursion-omission: strategy: absent required: - file type: object additionalProperties: false File: description: >- A file object: bytes uploaded once and attachable to any number of sessions as a resource, or bytes a session produced. Attaching a file mounts it read-only into the session's sandbox at a path the session is told about. properties: byte_size: description: Size of the file in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 created_at: description: Server-assigned RFC 3339 timestamp of the upload. format: date-time type: string downloadable: description: >- Whether GET /managed-agents/v1/files/{fileId}/content serves the bytes. True for every live file, upload or session output; expiry, not source, is what closes the content route. type: boolean expires_at: description: >- When the file stops being attachable and its content stops being served. Its metadata stays readable and listed, with this in the past, for a grace before the file is reclaimed. Absent means it does not expire. format: date-time type: string file_id: description: >- Server-assigned id, used to attach the file to a session as a resource. type: string filename: description: >- The name the file was uploaded under, without any directory. This is the name it is mounted under in a sandbox unless a resource says otherwise. type: string media_type: description: >- The upload's declared Content-Type. When the part declared none, or declared application/octet-stream, the type is detected from the filename's extension, through a fixed table rather than the host's, and then from the bytes, falling back to application/octet-stream when neither says anything. Informational: the platform does not transcode or validate against it. type: string metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Caller-owned key/value data stored with the file and returned unchanged. type: object organization_id: description: >- Organization that owns the file. Server-assigned from the caller's credentials. type: string ownerAgentId: description: >- For a session output, the agent whose file history holds it: the agent the root session ran, including outputs its subagents and teammates saved. Absent on uploads and on outputs of sessions not started from an agent. type: string producerAgentVersionId: description: >- For a session output, the agent version the writing session ran. Absent for outputs saved before it was recorded. type: string producerSessionId: description: >- For a session output, the session in the tree that wrote it, which is a subagent or teammate when not the root. type: string scope_session_id: description: >- For a session output, the session that produced it. Absent on an upload, which belongs to the organization rather than to any one session. type: string sha256: description: SHA-256 of the file's contents, for checking a download. type: string source: description: >- How the file came to exist: upload for a file you uploaded, session_output for a deliverable a session saved. enum: - upload - session_output type: string type: description: Always file. enum: - file type: string required: - type - organization_id - file_id - filename - media_type - byte_size - sha256 - source - downloadable - created_at 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. 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. ManagedAgentsApiErrorFileQuotaExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - file_quota_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. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. 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. 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. 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. 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 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. ````