Open Response API Documentation

The Vector Store API enables you to create and manage vector stores—specialized collections that transform your documents into searchable embeddings for semantic retrieval.

The official documentation for the Vector Store API is available here.

Key Concepts

Vector Stores

Collections that organize and index document embeddings

Document Embeddings

Numerical representations of document content that capture semantic meaning

Chunking Strategies

Methods for dividing documents into semantically meaningful segments

File Attributes

Metadata tags that enable filtering and organizing documents

API Endpoints

Create a Vector Store

Create a new vector store to hold document embeddings.

Endpoint: POST /v1/vector_stores
Content-Type: application/json

Request Body:

name: Name of the vector store (required)
metadata: Custom metadata for the vector store (optional)

curl --location 'http://localhost:8080/v1/vector_stores' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "name": "Technical Documentation"
}'

Example Response:

{
    "id": "vs_67f802071ad5d3000001",
    "object": "vector_store",
    "created_at": 1744306695,
    "name": "Technical Documentation",
    "bytes": 0,
    "file_counts": {
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "total": 0
    },
    "last_active_at": 1744306695,
    "status": "in_progress"
}

List Vector Stores

Retrieve a list of all your vector stores.

Endpoint: GET /v1/vector_stores

Query Parameters:

limit: Maximum number of vector stores to return (default: 20, range: 1-100)
after: Return vector stores after this ID for pagination (optional)

curl --location 'http://localhost:8080/v1/vector_stores?limit=10' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "data": [
        {
            "id": "vs_67f802071ad5d3000001",
            "object": "vector_store",
            "created_at": 1744306695,
            "name": "Technical Documentation",
            "bytes": 0,
            "file_counts": {
                "in_progress": 0,
                "completed": 0,
                "failed": 0,
                "cancelled": 0,
                "total": 0
            },
            "last_active_at": 1744306695,
            "status": "in_progress"
        }
    ],
    "object": "list",
    "first_id": "vs_67f802071ad5d3000001",
    "last_id": "vs_67f802071ad5d3000001",
    "has_more": true
}

Retrieve a Vector Store

Get details about a specific vector store.

Endpoint: GET /v1/vector_stores/{vector_store_id}

Path Parameters:

vector_store_id: The ID of the vector store to retrieve (required)

curl --location 'http://localhost:8080/v1/vector_stores/vs_abc123' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "id": "vs_67f802071ad5d3000001",
    "object": "vector_store",
    "created_at": 1744306695,
    "name": "Technical Documentation",
    "bytes": 0,
    "file_counts": {
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "total": 0
    },
    "last_active_at": 1744306695,
    "status": "in_progress"
}

Update a Vector Store

Update the metadata of a vector store.

Endpoint: PATCH /v1/vector_stores/{vector_store_id}
Content-Type: application/json

Path Parameters:

vector_store_id: The ID of the vector store to update (required)

Request Body:

name: New name for the vector store (optional)
metadata: New custom metadata for the vector store (optional)

curl --location --request POST 'http://localhost:8080/v1/vector_stores/vs_67f802071ad5d3000001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "name": "Updated Technical Documentation",
  "metadata": {
    "department": "History",
    "access_level": "internal"
  }
}'

Example Response:

{
    "id": "vs_67f802071ad5d3000001",
    "object": "vector_store",
    "created_at": 1744306695,
    "name": "Updated Technical Documentation",
    "bytes": 0,
    "file_counts": {
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "total": 0
    },
    "last_active_at": 1744306902,
    "status": "in_progress",
    "metadata": {
        "department": "History",
        "access_level": "internal"
    }
}

Delete a Vector Store

Delete a vector store and all its files.

Endpoint: DELETE /v1/vector_stores/{vector_store_id}

Path Parameters:

vector_store_id: The ID of the vector store to delete (required)

curl --location --request DELETE 'http://localhost:8080/v1/vector_stores/vs_abc123' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "id": "vs_67f802071ad5d3000001",
    "object": "vector_store.deleted",
    "deleted": true
}

Deleting a vector store permanently removes all associated file embeddings. The original files in the Files API are not affected.

Example Implementation

For a complete working example of how to use the Vector Store API, check out this Python example on GitHub. This example demonstrates:

Creating vector stores for document collections
Adding files to vector stores with custom chunking strategies
Managing vector store metadata and attributes
Integrating with search tools like AgenticSearchTool and FileSearchTool
Working with the OpenAI Agents SDK for RAG applications

Working with Vector Store Files

Add a File to a Vector Store

Add a file to a vector store for embedding and semantic search.

Endpoint: POST /v1/vector_stores/{vector_store_id}/files
Content-Type: application/json

Path Parameters:

vector_store_id: The ID of the vector store to add the file to (required)

Request Body:

file_id: ID of the file to add (required)
chunking_strategy: Strategy for dividing the document (optional)
attributes: Custom attributes for filtering (optional)

curl --location 'http://localhost:8080/v1/vector_stores/vs_abc123/files' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
  "file_id": "file_def456",
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 1000,
      "chunk_overlap_tokens": 200
    }
  },
  "attributes": {
    "category": "api_reference",
    "language": "en",
    "version": "2.0"
  }
}'

Example Response:

{
    "id": "open-responses-file_67f803701ad5d3000002.pdf",
    "object": "vector_store.file",
    "created_at": 1744307109,
    "usage_bytes": 422718,
    "vector_store_id": "vs_67f65468f25fcc000001",
    "status": "in_progress",
    "chunking_strategy": {
        "type": "static",
        "static": {
            "max_chunk_size_tokens": 1000,
            "chunk_overlap_tokens": 200
        }
    },
    "attributes": {
        "category": "api_reference",
        "language": "en",
        "version": "2.0",
        "filename": "Empress Matilda.pdf"
    }
}

File processing happens asynchronously. The initial status will be “in_progress”, and you’ll need to check again later for the completed status.

List Files in a Vector Store

Retrieve a list of all files in a vector store.

Endpoint: GET /v1/vector_stores/{vector_store_id}/files

Path Parameters:

vector_store_id: The ID of the vector store to list files from (required)

Query Parameters:

limit: Maximum number of files to return (default: 20, range: 1-100)
after: Return files after this ID for pagination (optional)

curl --location 'http://localhost:8080/v1/vector_stores/vs_abc123/files?limit=10' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "data": [
        {
            "id": "open-responses-file_67f803701ad5d3000002.pdf",
            "object": "vector_store.file",
            "created_at": 1744307397,
            "usage_bytes": 422718,
            "vector_store_id": "vs_67f8046b1ad5d3000012",
            "status": "completed",
            "chunking_strategy": {
                "type": "static",
                "static": {
                    "max_chunk_size_tokens": 1000,
                    "chunk_overlap_tokens": 200
                }
            },
            "attributes": {
                "category": "api_reference",
                "language": "en",
                "version": "2.0",
                "filename": "Empress Matilda.pdf"
            }
        }
    ],
    "object": "list",
    "first_id": "open-responses-file_67f803701ad5d3000002.pdf",
    "last_id": "open-responses-file_67f803701ad5d3000002.pdf",
    "has_more": false
}

Retrieve a File in a Vector Store

Get details about a specific file in a vector store.

Endpoint: GET /v1/vector_stores/{vector_store_id}/files/{file_id}

Path Parameters:

vector_store_id: The ID of the vector store (required)
file_id: The ID of the file to retrieve (required)

curl --location 'http://localhost:8080/v1/vector_stores/vs_abc123/files/vsfile_ghi789' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

{
    "id": "open-responses-file_67f803701ad5d3000002.pdf",
    "object": "vector_store.file",
    "created_at": 1744307397,
    "usage_bytes": 422718,
    "vector_store_id": "vs_67f8046b1ad5d3000012",
    "status": "completed",
    "chunking_strategy": {
        "type": "static",
        "static": {
            "max_chunk_size_tokens": 1000,
            "chunk_overlap_tokens": 200
        }
    },
    "attributes": {
        "category": "api_reference",
        "language": "en",
        "version": "2.0",
        "filename": "Empress Matilda.pdf"
    }
}

Delete a File from a Vector Store

Remove a file from a vector store.

Endpoint: DELETE /v1/vector_stores/{vector_store_id}/files/{file_id}

Path Parameters:

vector_store_id: The ID of the vector store (required)
file_id: The ID of the file to remove (required)

curl --location --request DELETE 'http://localhost:8080/v1/vector_stores/vs_abc123/files/vsfile_ghi789' \
--header 'Authorization: Bearer $YOUR_API_KEY'

Example Response:

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

Advanced Features

Chunking Strategies

Chunking strategies determine how documents are divided for embedding and retrieval:

Divides documents into fixed-size chunks with configurable overlap:

"chunking_strategy": {
  "type": "static",
  "static": {
    "max_chunk_size_tokens": 1000,
    "chunk_overlap_tokens": 200
  }
}

Good for general-purpose document processing.

Divides documents into fixed-size chunks with configurable overlap:

"chunking_strategy": {
  "type": "static",
  "static": {
    "max_chunk_size_tokens": 1000,
    "chunk_overlap_tokens": 200
  }
}

Good for general-purpose document processing.

Attempts to divide documents along natural sentence boundaries:

"chunking_strategy": {
  "type": "sentence",
  "sentence": {
    "max_chunk_size_tokens": 1500,
    "chunk_overlap_tokens": 200
  }
}

Better for technical documents with code blocks and equations.

Attempts to divide documents along natural paragraph boundaries:

"chunking_strategy": {
  "type": "paragraph",
  "paragraph": {
    "max_chunk_size_tokens": 1500,
    "chunk_overlap_tokens": 200
  }
}

Better for preserving context in narrative documents.

File Attributes

File attributes enable filtering and organization of documents within a vector store:

"attributes": {
  "category": "api_reference",
  "language": "en",
  "version": "2.0",
  "department": "Engineering",
  "access_level": "public"
}

These attributes can later be used as filters in search queries to narrow down results.

Best Practices

Vector Store Organization

Create separate vector stores for different domains

Use meaningful names and descriptions

Leverage metadata for additional context

File Management

Use consistent attribute schemes

Include version information

Update attributes as files change

Chunking Strategy

Technical documentation

Narrative content

Tabular/structured data

Include overlap between chunks

Performance Considerations

Keep file count per vector store reasonable (less than 10,000 files for optimal performance)
Use pagination when listing files in large vector stores
Add files in batches rather than one by one for large collections

Files API

Upload and manage files before adding to vector stores

Search API

Search vector stores for relevant content

Get Started

Announcements

Model Providers

Use Cases & Demos

OpenResponses API

Retrieval (RAG)

Built-In Tools

Vector Store API

Key Concepts

Vector Stores

Document Embeddings

Chunking Strategies

File Attributes

API Endpoints

Create a Vector Store

List Vector Stores

Retrieve a Vector Store

Update a Vector Store

Delete a Vector Store

Example Implementation

Working with Vector Store Files

Add a File to a Vector Store

List Files in a Vector Store

Retrieve a File in a Vector Store

Delete a File from a Vector Store

Advanced Features

Chunking Strategies

File Attributes

Best Practices

Vector Store Organization

File Management

Chunking Strategy

Performance Considerations

Files API

Search API

Get Started

Announcements

Model Providers

Use Cases & Demos

OpenResponses API

Retrieval (RAG)

Built-In Tools

​Key Concepts

Vector Stores

Document Embeddings

Chunking Strategies

File Attributes

​API Endpoints

​Create a Vector Store

​List Vector Stores

​Retrieve a Vector Store

​Update a Vector Store

​Delete a Vector Store

​Example Implementation

​Working with Vector Store Files

​Add a File to a Vector Store

​List Files in a Vector Store

​Retrieve a File in a Vector Store

​Delete a File from a Vector Store

​Advanced Features

​Chunking Strategies

​File Attributes

​Best Practices

​Vector Store Organization

​File Management

​Chunking Strategy

​Performance Considerations

​Related APIs

Files API

Search API

Key Concepts

API Endpoints

Create a Vector Store

List Vector Stores

Retrieve a Vector Store

Update a Vector Store

Delete a Vector Store

Example Implementation

Working with Vector Store Files

Add a File to a Vector Store

List Files in a Vector Store

Retrieve a File in a Vector Store

Delete a File from a Vector Store

Advanced Features

Chunking Strategies

File Attributes

Best Practices

Vector Store Organization

File Management

Chunking Strategy

Performance Considerations

Related APIs