The Files API allows you to upload, manage, and retrieve documents for use with the RAG system. This API serves as the foundation for document management before semantic search. The official documentation for the Files API is available here.

​
Key Capabilities

Document Upload

Upload documents in various formats (PDF, TXT, DOCX, CSV, JSON, etc.)

File Management

List, retrieve, and delete files with filtering options

Content Access

Access file content and metadata through a unified API

RAG Integration

Seamlessly connect with vector stores for embedding generation

​
API Endpoints

​
Upload a File

Upload a document to make it available for vector stores and semantic search. Endpoint: POST /v1/files
Content-Type: multipart/form-data Request Parameters:
  • file: The file to upload (required)
  • purpose: The intended use of the file (required)
    • Supported values: assistants, batch, fine_tune, vision, user_data, evals
curl --location 'http://localhost:6644/v1/files' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--form 'file=@"/path/to/your/document.pdf"' \
--form 'purpose="user_data"'
Example Response: 
{
  "id": "file_abc123",
  "object": "file",
  "bytes": 0,
  "created_at": 1677610602,
  "filename": "document.pdf",
  "purpose": "user_data"
}
Supported formats include PDF, TXT, DOCX, CSV, JSON, and many others. The returned file ID is used for all other operations with this file. The bytes field will be 0 until the file is processed.

​
List Files

Retrieve a list of all files you’ve uploaded, with optional filtering. Endpoint: GET /v1/files Query Parameters:
  • purpose: Filter files by purpose (optional)
  • limit: Maximum number of files to return (default: 100, range: 1-100)
  • order: Sort order by creation timestamp (asc or desc, default: desc)
  • after: Return files after this ID for pagination (optional)
curl --location 'http://localhost:6644/v1/files?purpose=user_data&limit=10&order=desc' \
--header 'Authorization: Bearer $YOUR_API_KEY'
Example Response: 
{
    "data": [
        {
            "id": "open-responses-file_67f800891ad5d3000000.pdf",
            "object": "file",
            "bytes": 422718,
            "created_at": 1744306313,
            "filename": "Empress Matilda.pdf",
            "purpose": "user_data",
            "status": "processed"
        }
    ],
    "object": "list"
}

​
Retrieve File Metadata

Get metadata about a specific file. Endpoint: GET /v1/files/{file_id} Path Parameters:
  • file_id: The ID of the file to retrieve (required)
curl --location 'http://localhost:6644/v1/files/file_abc123' \
--header 'Authorization: Bearer $YOUR_API_KEY'
Example Response: 
{
    "id": "open-responses-file_67f800891ad5d3000000.pdf",
    "object": "file",
    "bytes": 422718,
    "created_at": 1744306313,
    "filename": "Empress Matilda.pdf",
    "purpose": "user_data",
    "status": "processed"
}

​
Retrieve File Content

Download the content of a specific file. Endpoint: GET /v1/files/{file_id}/content Path Parameters:
  • file_id: The ID of the file to retrieve (required)
curl --location 'http://localhost:6644/v1/files/file_abc123/content' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--output downloaded_document.pdf
Response: The file content with appropriate Content-Type header.

​
Delete a File

Delete a file when it’s no longer needed. Endpoint: DELETE /v1/files/{file_id} Path Parameters:
  • file_id: The ID of the file to delete (required)
curl --location --request DELETE 'http://localhost:6644/v1/files/file_abc123' \
--header 'Authorization: Bearer $YOUR_API_KEY'
Example Response: 
{
    "id": "open-responses-file_67f800891ad5d3000000.pdf",
    "object": "file",
    "deleted": true
}
Deleting a file will also remove it from any vector stores it has been added to.

​
Using Files with Vector Stores

After uploading a file, you can add it to a vector store for semantic search. This workflow connects the Files API to the Vector Store API.
1

Upload a File

Use the Files API to upload your document
curl --location 'http://localhost:6644/v1/files' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--form 'file=@"/path/to/your/document.pdf"' \
--form 'purpose="user_data"'
2

Create a Vector Store

If you don’t already have a vector store, create one
curl --location 'http://localhost:6644/v1/vector_stores' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "name": "My Knowledge Base",
  "description": "Technical documentation"
}'
3

Add the File to Vector Store

Add your uploaded file to the vector store
curl --location 'http://localhost:6644/v1/vector_stores/vs_def456/files' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "file_id": "file_abc123",
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 1000,
      "chunk_overlap_tokens": 200
    }
  }
}'
4

Search for Content

Now you can search for content in your documents
curl --location 'http://localhost:6644/v1/vector_stores/vs_def456/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "query": "How do I configure the system?"
}'

​
Example Implementation

For a complete working example of how to use the Files API with vector stores and search functionality, check out this Python example on GitHub. This example demonstrates:
  • Uploading files to the OpenResponses API
  • Creating vector stores
  • Adding files to vector stores for embedding
  • Searching the vector store with different tools
  • Using both direct API calls and the OpenAI Agents SDK

​
Best Practices

​
File Organization

​
File Management

  • Regularly review and clean up unused files to maintain optimal performance
  • Use the purpose parameter to categorize files based on their intended use
  • Leverage file metadata for tracking document versions and categories
  • Consider creating a file inventory system for larger implementations

Vector Store API

Create and manage vector stores for your files

Search API

Search across your document collections