Files API

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

​

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:8080/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"
}

​

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:8080/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:8080/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:8080/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:8080/v1/files/file_abc123' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "id": "open-responses-file_67f800891ad5d3000000.pdf",
    "object": "file",
    "deleted": true
}

​

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.

curl --location 'http://localhost:8080/v1/files' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--form 'file=@"/path/to/your/document.pdf"' \
--form 'purpose="user_data"'

curl --location 'http://localhost:8080/v1/vector_stores' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "name": "My Knowledge Base",
  "description": "Technical documentation"
}'

curl --location 'http://localhost:8080/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
    }
  }
}'

curl --location 'http://localhost:8080/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

​

Related APIs