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:6644/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:6644/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:6644/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:6644/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:6644/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:6644/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:6644/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:6644/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:6644/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.

​
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

​
File Management

​
Chunking Strategy

​
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