Uploads API - DeerFlow

Overview

The Uploads API provides endpoints to upload, list, and delete files for specific threads. Uploaded files are stored in thread-specific directories and can be accessed by AI agents. Certain file types (PDF, Office documents) are automatically converted to markdown.

Upload Files

POST /api/threads/{thread_id}/uploads

Upload multiple files to a thread’s uploads directory

Path Parameters

thread_id

string

required

The thread ID to upload files to

Request Body

Multipart form data with one or more files:

files

file[]

required

List of files to upload (multipart/form-data)

Response

success

boolean

required

Whether the upload was successful

files

array

required

List of uploaded file information

Show File Info Object

filename

string

required

Name of the uploaded file

size

string

required

File size in bytes (as string)

path

string

required

Actual filesystem path (relative to backend/)

virtual_path

string

required

Path for Agent in sandbox (e.g., /mnt/user-data/uploads/file.txt)

artifact_url

string

required

HTTP URL to access the file via artifacts API

markdown_file

string

Name of converted markdown file (if applicable)

markdown_path

string

Filesystem path to markdown file

markdown_virtual_path

string

Virtual path to markdown file in sandbox

markdown_artifact_url

string

HTTP URL to access the markdown file

message

string

required

Success message with upload count

Example Request

curl -X POST http://localhost:8001/api/threads/abc123/uploads \
  -F "files=@document.pdf" \
  -F "files=@image.png" \
  -F "files=@data.csv"

Example Response

{
  "success": true,
  "files": [
    {
      "filename": "document.pdf",
      "size": "1048576",
      "path": "sandbox/threads/abc123/uploads/document.pdf",
      "virtual_path": "/mnt/user-data/uploads/document.pdf",
      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
      "markdown_file": "document.md",
      "markdown_path": "sandbox/threads/abc123/uploads/document.md",
      "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
      "markdown_artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.md"
    },
    {
      "filename": "image.png",
      "size": "524288",
      "path": "sandbox/threads/abc123/uploads/image.png",
      "virtual_path": "/mnt/user-data/uploads/image.png",
      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/image.png"
    },
    {
      "filename": "data.csv",
      "size": "2048",
      "path": "sandbox/threads/abc123/uploads/data.csv",
      "virtual_path": "/mnt/user-data/uploads/data.csv",
      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/data.csv"
    }
  ],
  "message": "Successfully uploaded 3 file(s)"
}

Auto-Conversion to Markdown

The following file types are automatically converted to markdown using markitdown:

.pdf - PDF documents
.ppt, .pptx - PowerPoint presentations
.xls, .xlsx - Excel spreadsheets
.doc, .docx - Word documents

Both the original file and the converted markdown file are saved and accessible.

Error Responses

400

Bad Request

No files provided or invalid filename

{
  "detail": "No files provided"
}

500

Internal Server Error

Upload failed

{
  "detail": "Failed to upload file.pdf: [error details]"
}

Security

Filenames are sanitized to prevent path traversal attacks
Only the filename component is used (directory paths are stripped)
Files with unsafe names (., .., containing / or \) are rejected

List Uploaded Files

GET /api/threads/{thread_id}/uploads/list

List all files in a thread’s uploads directory

Path Parameters

thread_id

string

required

The thread ID to list files for

Response

files

array

required

List of files with metadata

Show File Object

filename

string

required

Name of the file

size

integer

required

File size in bytes

path

string

required

Actual filesystem path

virtual_path

string

required

Path for Agent in sandbox

artifact_url

string

required

HTTP URL to access the file

extension

string

required

File extension (e.g., .pdf, .png)

modified

number

required

Last modified timestamp (Unix timestamp)

count

integer

required

Total number of files

Example Request

curl http://localhost:8001/api/threads/abc123/uploads/list

Example Response

{
  "files": [
    {
      "filename": "document.pdf",
      "size": 1048576,
      "path": "sandbox/threads/abc123/uploads/document.pdf",
      "virtual_path": "/mnt/user-data/uploads/document.pdf",
      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
      "extension": ".pdf",
      "modified": 1705318200.0
    },
    {
      "filename": "document.md",
      "size": 4096,
      "path": "sandbox/threads/abc123/uploads/document.md",
      "virtual_path": "/mnt/user-data/uploads/document.md",
      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.md",
      "extension": ".md",
      "modified": 1705318201.0
    }
  ],
  "count": 2
}

Empty Directory

If no files have been uploaded:

{
  "files": [],
  "count": 0
}

Delete Uploaded File

DELETE /api/threads/{thread_id}/uploads/{filename}

Delete a file from a thread’s uploads directory

Path Parameters

thread_id

string

required

The thread ID

filename

string

required

The filename to delete

Response

success

boolean

required

Whether the deletion was successful

message

string

required

Success message

Example Request

curl -X DELETE http://localhost:8001/api/threads/abc123/uploads/document.pdf

Example Response

{
  "success": true,
  "message": "Deleted document.pdf"
}

Error Responses

403

Forbidden

Access denied (path traversal attempt)

{
  "detail": "Access denied"
}

404

Not Found

File not found

{
  "detail": "File not found: document.pdf"
}

500

Internal Server Error

Deletion failed

{
  "detail": "Failed to delete document.pdf: [error details]"
}

File Storage

Directory Structure

backend/
└── sandbox/
    └── threads/
        └── {thread_id}/
            └── uploads/
                ├── document.pdf
                ├── document.md  (auto-converted)
                ├── image.png
                └── data.csv

Virtual Paths

Files are accessible to AI agents via virtual paths:

/mnt/user-data/uploads/{filename}

Agents can read and process these files using their file tools.

Sandbox Synchronization

For non-local sandboxes (e.g., E2B), files are automatically synced:

Upload: Files are saved to host storage and synced to sandbox
Agent Access: Agents read files from sandbox virtual paths
Source of Truth: Host storage remains the source of truth

Use Cases

Upload Files from Frontend

async function uploadFiles(threadId: string, files: File[]) {
  const formData = new FormData();
  files.forEach(file => {
    formData.append('files', file);
  });
  
  const response = await fetch(
    `http://localhost:8001/api/threads/${threadId}/uploads`,
    {
      method: 'POST',
      body: formData
    }
  );
  
  return response.json();
}

List and Display Files

async function listFiles(threadId: string) {
  const response = await fetch(
    `http://localhost:8001/api/threads/${threadId}/uploads/list`
  );
  const { files, count } = await response.json();
  
  return files.map(file => ({
    name: file.filename,
    size: file.size,
    url: `http://localhost:8001${file.artifact_url}`,
    modified: new Date(file.modified * 1000)
  }));
}

Delete File

async function deleteFile(threadId: string, filename: string) {
  const response = await fetch(
    `http://localhost:8001/api/threads/${threadId}/uploads/${filename}`,
    { method: 'DELETE' }
  );
  return response.json();
}

Access Uploaded Files

After uploading, files can be accessed via:

Artifacts API: GET /api/threads/{thread_id}/artifacts/mnt/user-data/uploads/{filename}
Agent Tools: Agents can read files using their virtual paths

// Download file
const response = await fetch(
  `http://localhost:8001/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf?download=true`
);
const blob = await response.blob();

Artifacts API

Access uploaded files

Gateway Overview

Learn about the Gateway API

Python Client

Gateway API

LangGraph API

Agent Tools

Documentation Index

​Overview

​Upload Files

POST /api/threads/{thread_id}/uploads

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Auto-Conversion to Markdown

​Error Responses

​Security

​List Uploaded Files

GET /api/threads/{thread_id}/uploads/list

​Path Parameters

​Response

​Example Request

​Example Response

​Empty Directory

​Delete Uploaded File

DELETE /api/threads/{thread_id}/uploads/{filename}

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​File Storage

​Directory Structure

​Virtual Paths

​Sandbox Synchronization

​Use Cases

​Upload Files from Frontend

​List and Display Files

​Delete File

​Access Uploaded Files

​Related

Artifacts API

Gateway Overview

Build docs developers (and LLMs) love

Overview

Upload Files

Path Parameters

Request Body

Response

Example Request

Example Response

Auto-Conversion to Markdown

Error Responses

Security

List Uploaded Files

Path Parameters

Response

Example Request

Example Response

Empty Directory

Delete Uploaded File

Path Parameters

Response

Example Request

Example Response

Error Responses

File Storage

Directory Structure

Virtual Paths

Sandbox Synchronization

Use Cases

Upload Files from Frontend

List and Display Files

Delete File

Access Uploaded Files

Related