Files API

The Files API allows you to upload files for use with agents, assistants, and conversations, as well as manage and download files. Supports multiple storage strategies including local, S3, Azure Blob, and OpenAI storage.

Authentication

All endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <your_jwt_token>

List Files

curl -X GET "https://your-domain.com/api/files" \
  -H "Authorization: Bearer <token>"

Retrieve all files uploaded by the authenticated user.

Response

Returns an array of file objects. S3 URLs are automatically refreshed if expired.

files

array

Show File object

file_id

string

Unique file identifier

filename

string

Original filename

filepath

string

Storage path or URL

bytes

integer

File size in bytes

type

string

MIME type

source

string

Storage source (“local”, “s3”, “azure”, “openai”, etc.)

context

string

File context (“message_attachment”, “agents”, “assistants”)

embedded

boolean

Whether the file has been embedded/processed

usage

number

Usage count or token count

createdAt

string

ISO 8601 timestamp

updatedAt

string

ISO 8601 timestamp

expiresAt

string

Expiration timestamp (for temporary files)

Get Agent Files

curl -X GET "https://your-domain.com/api/files/agent/<agent_id>" \
  -H "Authorization: Bearer <token>"

Retrieve files attached to a specific agent. Requires EDIT permission on the agent.

Path Parameters

agent_id

string

required

The agent ID

Response

Returns an array of file objects attached to the agent via tool_resources (file_search, code_interpreter).

Get File Configuration

curl -X GET "https://your-domain.com/api/files/config" \
  -H "Authorization: Bearer <token>"

Retrieve the server’s file upload configuration (limits, allowed types, etc.).

Response

serverFileSizeLimit

integer

Maximum file size in bytes

avatarSizeLimit

integer

Maximum avatar size in bytes

endpoints

object

Per-endpoint file configuration

Show Endpoint config

disabled

boolean

Whether file uploads are disabled for this endpoint

fileLimit

integer

Maximum number of files per upload

fileSizeLimit

integer

Maximum file size in bytes

totalSizeLimit

integer

Maximum total size for all files

supportedMimeTypes

array

Array of supported MIME type patterns

Upload File

curl -X POST "https://your-domain.com/api/files" \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf" \
  -F "endpoint=agents" \
  -F "agent_id=<agent_id>" \
  -F "tool_resource=file_search" \
  -F "message_file=false"

Upload a file for use with agents, assistants, or as a message attachment. Rate limited.

Request

Multipart form data with file and metadata fields.

file

required

The file to upload

endpoint

string

Endpoint the file is for (“agents”, “assistants”, “openAI”, etc.)

agent_id

string

Agent ID (if attaching to an agent)

assistant_id

string

Assistant ID (if attaching to an assistant)

tool_resource

string

Tool resource type: “file_search” or “code_interpreter”

message_file

boolean

default:"false"

Whether this is a temporary message attachment (true) or permanent agent file (false)

conversationId

string

Conversation ID for message attachments

file_id

string

Optional custom file ID (UUID generated if omitted)

Response

Returns the uploaded file object.

Permissions

Permanent agent file uploads (message_file=false) require:

User must be agent author OR
User must have EDIT permission on the agent
Admin users bypass permission checks

Message attachments (message_file=true) require only chat access.

Error Responses

400 Bad Request: Invalid file format or exceeds limits
403 Forbidden: Insufficient permissions to upload to agent
404 Not Found: Agent not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Upload failed

Download File

curl -X GET "https://your-domain.com/api/files/download/<user_id>/<file_id>" \
  -H "Authorization: Bearer <token>" \
  -o downloaded_file

Download a file. Access is validated by middleware.

Path Parameters

userId

string

required

User ID of the file owner

file_id

string

required

The file ID

Response

Returns the file as an octet-stream with appropriate headers:

Content-Disposition: attachment with filename
Content-Type: application/octet-stream
X-File-Metadata: JSON metadata about the file

Error Responses

400 Bad Request: File model not available or invalid request
403 Forbidden: User lacks access to the file
404 Not Found: File not found
500 Internal Server Error: Download failed
501 Not Implemented: Storage strategy doesn’t support downloads

Download Code Output File

curl -X GET "https://your-domain.com/api/files/code/download/<session_id>/<file_id>" \
  -H "Authorization: Bearer <token>" \
  -o output_file

Download a file generated by code execution (code interpreter tool).

Path Parameters

session_id

string

required

Code execution session ID (21 characters, base64url)

fileId

string

required

File ID within the session (21 characters, base64url)

Response

Streams the file content with appropriate headers from the code execution service.

Error Responses

400 Bad Request: Invalid session_id or fileId
500 Internal Server Error: Download failed
501 Not Implemented: Storage strategy doesn’t support this operation

Delete Files

curl -X DELETE "https://your-domain.com/api/files" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "file_id": "<file_id>",
        "filepath": "<filepath>",
        "embedded": false,
        "source": "local"
      }
    ],
    "agent_id": "<agent_id>",
    "tool_resource": "file_search"
  }'

Delete one or more files. Supports bulk deletion and unlinking from agents/assistants.

Request Body

files

array

required

Array of file objects to delete

Show File object

file_id

string

required

File ID (must be valid UUID or OpenAI file ID format)

filepath

string

required

File path or URL

embedded

boolean

Whether the file is embedded

source

string

Storage source

agent_id

string

Agent ID (for unlinking files from agents)

assistant_id

string

Assistant ID (for unlinking files from assistants)

tool_resource

string

Tool resource type: “file_search” or “code_interpreter”

Response

message

string

Success message

Permission Handling

Users can always delete their own files
Non-owned files require access via agent (EDIT permission for deletion)
If agent_id is provided, checks if user has access to delete files via that agent

Error Responses

204 No Content: Nothing provided to delete
403 Forbidden: User lacks access to delete one or more files
500 Internal Server Error: Deletion failed

File Sources

LibreChat supports multiple file storage strategies:

Source	Description
`local`	Local filesystem storage
`s3`	AWS S3 bucket
`azure_blob`	Azure Blob Storage
`firebase`	Firebase Storage
`openai`	OpenAI API file storage
`azure`	Azure OpenAI file storage
`vectordb`	Vector database (for embeddings)
`execute_code`	Code execution output files
`mistral_ocr`	Mistral OCR processed files
`text`	Text extraction service
`document_parser`	Document parsing service

File Contexts

Files can have different contexts indicating their usage:

Context	Description
`message_attachment`	Temporary file attached to a message
`agents`	File uploaded to an agent’s tool resources
`assistants`	File uploaded to an assistant
`assistants_output`	File generated by an assistant
`execute_code`	Code execution output
`image_generation`	Generated image
`avatar`	User or agent avatar image

Common Error Codes

Status Code	Description
400	Bad Request - Invalid file format, exceeds limits, or invalid parameters
401	Unauthorized - Invalid or missing JWT token
403	Forbidden - User lacks permission to access or modify the file
404	Not Found - File or agent/assistant not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Upload, download, or deletion failed
501	Not Implemented - Storage strategy doesn’t support the operation

Overview

Endpoints

Authentication

List Files

Response

Get Agent Files

Path Parameters

Response

Get File Configuration

Response

Upload File

Request

Response

Permissions

Error Responses

Download File

Path Parameters

Response

Error Responses

Download Code Output File

Path Parameters

Response

Error Responses

Delete Files

Request Body

Response

Permission Handling

Error Responses

File Sources

File Contexts

Common Error Codes

Overview

Endpoints

​Authentication

​List Files

​Response

​Get Agent Files

​Path Parameters

​Response

​Get File Configuration

​Response

​Upload File

​Request

​Response

​Permissions

​Error Responses

​Download File

​Path Parameters

​Response

​Error Responses

​Download Code Output File

​Path Parameters

​Response

​Error Responses

​Delete Files

​Request Body

​Response

​Permission Handling

​Error Responses

​File Sources

​File Contexts

​Common Error Codes

Authentication

List Files

Response

Get Agent Files

Path Parameters

Response

Get File Configuration

Response

Upload File

Request

Response

Permissions

Error Responses

Download File

Path Parameters

Response

Error Responses

Download Code Output File

Path Parameters

Response

Error Responses

Delete Files

Request Body

Response

Permission Handling

Error Responses

File Sources

File Contexts

Common Error Codes