Files - LibreChat

Overview

The Files API allows you to upload, download, and manage files for use in conversations, agents, and assistants. All file endpoints are prefixed with /api/files.

Upload File

Upload a file to LibreChat:

POST /api/files
Authorization: Bearer <token>
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[binary file data]
--boundary
Content-Disposition: form-data; name="endpoint"

openAI
--boundary--

Request Body (Multipart Form Data)

file

File

required

File to upload

endpoint

string

Endpoint to associate file with (e.g., openAI, anthropic)

agent_id

string

Agent ID to attach file to

assistant_id

string

Assistant ID to attach file to

tool_resource

string

Tool resource type (e.g., code_interpreter, file_search)

message_file

boolean

Whether this is a temporary message attachment (vs permanent agent file)

file_id

string

Custom file ID (optional, will be auto-generated if not provided)

Response

file_id

string

Unique file identifier

filename

string

Original filename

filepath

string

Server file path

type

string

MIME type

bytes

number

File size in bytes

user

string

Owner user ID

createdAt

string

Upload timestamp

{
  "file_id": "file_abc123xyz",
  "filename": "document.pdf",
  "filepath": "/uploads/abc123/document.pdf",
  "type": "application/pdf",
  "bytes": 102400,
  "width": null,
  "height": null,
  "user": "user123",
  "createdAt": "2024-01-15T10:00:00Z",
  "source": "local"
}

List Files

Retrieve all files for the authenticated user:

GET /api/files
Authorization: Bearer <token>

Response

Returns an array of file objects:

[
  {
    "file_id": "file_abc123",
    "filename": "document.pdf",
    "type": "application/pdf",
    "bytes": 102400,
    "createdAt": "2024-01-15T10:00:00Z",
    "source": "local"
  },
  {
    "file_id": "file_xyz789",
    "filename": "image.png",
    "type": "image/png",
    "bytes": 51200,
    "width": 1024,
    "height": 768,
    "createdAt": "2024-01-14T09:00:00Z",
    "source": "local"
  }
]

Get Agent Files

Retrieve files attached to a specific agent:

GET /api/files/agent/:agent_id
Authorization: Bearer <token>

Path Parameters

agent_id

string

required

Agent ID

Response

Returns an array of files attached to the agent (excludes the text field for performance).

[
  {
    "file_id": "file_abc123",
    "filename": "knowledge_base.pdf",
    "type": "application/pdf",
    "bytes": 512000,
    "createdAt": "2024-01-10T08:00:00Z"
  }
]

Requires VIEW or EDIT permission on the agent.

Download File

Download a file:

GET /api/files/download/:userId/:file_id
Authorization: Bearer <token>

Path Parameters

userId

string

required

User ID who owns the file

file_id

string

required

File ID to download

Response

Returns the file with appropriate headers:

Content-Disposition: attachment; filename="document.pdf"
Content-Type: application/octet-stream
X-File-Metadata: {"file_id":"file_abc123",...}

[binary file data]

Download Code Output

Download output from code interpreter:

GET /api/files/code/download/:session_id/:fileId
Authorization: Bearer <token>

Path Parameters

session_id

string

required

Code execution session ID (21 characters, alphanumeric with - and _)

fileId

string

required

File ID from code execution (21 characters, alphanumeric with - and _)

Response

Streams the code output file.

Delete Files

Delete one or more files:

DELETE /api/files
Authorization: Bearer <token>
Content-Type: application/json

{
  "files": [
    {
      "file_id": "file_abc123",
      "filepath": "/uploads/abc123/document.pdf"
    }
  ],
  "agent_id": "agent_xyz",
  "tool_resource": "code_interpreter"
}

Request Body

files

object[]

required

Array of file objects to delete

files[].file_id

string

required

File ID (must be UUID or OpenAI format: file-*, assistant-*)

files[].filepath

string

required

File path on server

agent_id

string

Agent ID (for unlinking files from agent)

assistant_id

string

Assistant ID (for unlinking files from assistant)

tool_resource

string

Tool resource to unlink from (e.g., code_interpreter, file_search)

Response

{
  "message": "Files deleted successfully"
}

Authorization

Users can delete their own files
Users with EDIT permission on an agent can delete files attached to that agent
Users with EDIT permission on an assistant can delete files attached to that assistant

Get File Configuration

Retrieve file upload configuration:

GET /api/files/config
Authorization: Bearer <token>

Response

endpoints

object

File support configuration per endpoint

fileSizeLimit

number

Maximum file size in bytes

supportedMimeTypes

string[]

Supported MIME types

{
  "endpoints": {
    "openAI": {
      "fileLimit": 10,
      "fileSizeLimit": 10485760,
      "totalSizeLimit": 52428800,
      "supportedMimeTypes": [
        "image/png",
        "image/jpeg",
        "image/webp",
        "application/pdf",
        "text/plain"
      ]
    },
    "assistants": {
      "fileLimit": 20,
      "fileSizeLimit": 52428800,
      "supportedMimeTypes": ["*/*"]
    }
  },
  "fileSizeLimit": 10485760,
  "supportedMimeTypes": ["image/*", "application/pdf", "text/*"]
}

File Sources

LibreChat supports multiple file storage backends:

Local Storage

{
  "source": "local",
  "filepath": "/uploads/user123/file.pdf"
}

Amazon S3

{
  "source": "s3",
  "filepath": "s3://bucket/user123/file.pdf"
}

OpenAI Files

{
  "source": "openai",
  "file_id": "file-abc123xyz"
}

Azure OpenAI

{
  "source": "azure",
  "file_id": "assistant-abc123xyz"
}

Code Execution Output

{
  "source": "execute_code",
  "filepath": "session_id/file_id"
}

Supported File Types

Images

image/png
image/jpeg
image/webp
image/gif

Documents

application/pdf
text/plain
text/markdown
text/csv
application/json

Code Files

text/x-python
text/javascript
text/x-typescript
text/html
text/css

Office Documents

application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX)
application/vnd.openxmlformats-officedocument.presentationml.presentation (PPTX)

File Size Limits

Default limits (configurable per deployment):

Single file: 10 MB
Total per conversation: 50 MB
Assistant files: 50 MB per file
Images: 20 MB per file

Rate Limiting

File upload endpoints have specific rate limits:

IP-based limit: Protects against abuse from single IP
User-based limit: Limits uploads per authenticated user
Speech endpoints: Separate limits for STT/TTS

Error Responses

File Too Large

{
  "message": "Error processing file: File exceeds size limit",
  "error": "File too large"
}

HTTP Status: 500

Unsupported File Type

{
  "message": "Error processing file: Invalid file format",
  "error": "Unsupported file type"
}

HTTP Status: 500

Insufficient Permissions

{
  "error": "Forbidden",
  "message": "Insufficient permissions to upload files to this agent"
}

HTTP Status: 403

File Not Found

{
  "error": "File not found"
}

HTTP Status: 404

TypeScript Types

import type { TFile } from 'librechat-data-provider';

interface TFile {
  file_id: string;
  user: string;
  filename: string;
  filepath: string;
  type: string;
  bytes: number;
  width?: number;
  height?: number;
  source: FileSources;
  createdAt: string;
  updatedAt?: string;
}

Overview

Endpoints

Integration

​Overview

​Upload File

​Request Body (Multipart Form Data)

​Response

​List Files

​Response

​Get Agent Files

​Path Parameters

​Response

​Download File

​Path Parameters

​Response

​Download Code Output

​Path Parameters

​Response

​Delete Files

​Request Body

​Response

​Authorization

​Get File Configuration

​Response

​File Sources

​Local Storage

​Amazon S3

​OpenAI Files

​Azure OpenAI

​Code Execution Output

​Supported File Types

​Images

​Documents

​Code Files

​Office Documents

​File Size Limits

​Rate Limiting

​Error Responses

​File Too Large

​Unsupported File Type

​Insufficient Permissions

​File Not Found

​TypeScript Types

Build docs developers (and LLMs) love

Overview

Upload File

Request Body (Multipart Form Data)

Response

List Files

Response

Get Agent Files

Path Parameters

Response

Download File

Path Parameters

Response

Download Code Output

Path Parameters

Response

Delete Files

Request Body

Response

Authorization

Get File Configuration

Response

File Sources

Local Storage

Amazon S3

OpenAI Files

Azure OpenAI

Code Execution Output

Supported File Types

Images

Documents

Code Files

Office Documents

File Size Limits

Rate Limiting

Error Responses

File Too Large

Unsupported File Type

Insufficient Permissions

File Not Found

TypeScript Types