Mixedbread

Vector Stores

Overview

Vector stores provide a powerful way to manage document collections and perform semantic search across your content. A vector store acts as a container for your files, automatically generating embeddings and enabling advanced search capabilities.

Create Vector Store

POST/v1/vector_stores

Creates a new vector store to organize and search your document collections. You can optionally include files during creation or add them later.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Request Body

  • name
    name
    Type
    string
    Required or Optional
    optional
    A user-defined name for the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    A user-defined description for the vector store.
  • Defines the expiration policy for the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    A set of key-value pairs for storing custom information.
  • file_ids
    file_ids
    Type
    string[]
    Required or Optional
    optional
    A list of file IDs to initially add to the vector store.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    The name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    The description of the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The metadata associated with the vector store.
  • An object summarizing the status counts of files within the vector store.
  • The expiration policy defined for the vector store.
  • status
    status
    Type
    enum
    Required or Optional
    required
    The overall status of the vector store.
    Options:
    expiredin_progresscompleted
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the vector store was created.
  • updated_at
    updated_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the vector store was last updated.
  • last_active_at
    last_active_at
    Type
    string
    Required or Optional
    optional
    The timestamp indicating the last time the vector store was accessed.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    The total storage size used by the vector store in bytes.
  • expires_at
    expires_at
    Type
    string
    Required or Optional
    optional
    The calculated timestamp when the vector store will expire.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

Retrieve Vector Store

GET/v1/vector_stores/{vector_store_identifier}

Retrieves detailed information about a specific vector store, including file counts, status, and configuration.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store to retrieve.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    The name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    The description of the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The metadata associated with the vector store.
  • An object summarizing the status counts of files within the vector store.
  • The expiration policy defined for the vector store.
  • status
    status
    Type
    enum
    Required or Optional
    required
    The overall status of the vector store.
    Options:
    expiredin_progresscompleted
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the vector store was created.
  • updated_at
    updated_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the vector store was last updated.
  • last_active_at
    last_active_at
    Type
    string
    Required or Optional
    optional
    The timestamp indicating the last time the vector store was accessed.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    The total storage size used by the vector store in bytes.
  • expires_at
    expires_at
    Type
    string
    Required or Optional
    optional
    The calculated timestamp when the vector store will expire.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

Update Vector Store

PUT/v1/vector_stores/{vector_store_identifier}

Updates the metadata, name, description, or expiration policy of an existing vector store.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store to update.

Request Body

  • name
    name
    Type
    string
    Required or Optional
    optional
    The new name for the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    The new description for the vector store.
  • The new expiration policy for the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The new set of key-value pairs for storing custom information.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    The updated name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    The updated description of the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The updated metadata associated with the vector store.
  • The updated expiration policy defined for the vector store.
  • status
    status
    Type
    enum
    Required or Optional
    required
    The overall status of the vector store.
    Options:
    expiredin_progresscompleted
  • updated_at
    updated_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when this update occurred.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

List Vector Stores

GET/v1/vector_stores

Retrieves a paginated list of all vector stores in your account with summary information. Optionally filter results using a search query.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Query Parameters

  • q
    q
    Type
    string
    Required or Optional
    optional
    Search query for fuzzy matching over name and description fields.
  • limit
    limit
    Type
    integer
    Required or Optional
    optional
    The maximum number of items to return in the list.
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    The number of items to skip before starting the list.

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    The type of the response object.
  • data
    data
    Type
    VectorStore[]
    Required or Optional
    required
    A list containing the vector store objects.
  • An object containing pagination details for the list.

Delete Vector Store

DELETE/v1/vector_stores/{vector_store_identifier}

Permanently deletes a vector store and all associated files. This action cannot be undone.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store to delete.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The ID of the deleted vector store.
  • deleted
    deleted
    Type
    boolean
    Required or Optional
    required
    A boolean indicating whether the deletion was successful.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

Vector Store Files

These endpoints manage files within a specific vector store.

Create Vector Store File

POST/v1/vector_stores/{vector_store_identifier}/files

Adds an existing file to a vector store for indexing and search. The file will be processed asynchronously.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store to add the file to.

Request Body

  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    The identifier of the previously uploaded file to add.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Optional metadata specific to this file within the vector store.
  • An object containing experimental configuration options.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The identifier of the file within the vector store context.
  • filename
    filename
    Type
    string
    Required or Optional
    optional
    The name of the associated file.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The metadata associated with this file in the vector store.
  • status
    status
    Type
    enum
    Required or Optional
    required
    The processing status of this specific file within the vector store.
    Options:
    pendingin_progresscompletedfailedcancellederror
  • last_error
    last_error
    Type
    object
    Required or Optional
    optional
    An object containing details of the last processing error for this file.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    The identifier of the containing vector store.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the file was added to the vector store.
  • version
    version
    Type
    integer
    Required or Optional
    optional
    The version of the file that was added to the vector store.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    The storage size used by the file's indexed data in bytes.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

Retrieve Vector Store File

GET/v1/vector_stores/{vector_store_identifier}/files/{file_id}

Retrieves detailed information about a specific file within a vector store.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store containing the file.
  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    The unique identifier of the target file.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The identifier of the file within the vector store context.
  • filename
    filename
    Type
    string
    Required or Optional
    optional
    The name of the associated file.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    The metadata associated with this file in the vector store.
  • status
    status
    Type
    enum
    Required or Optional
    required
    The processing status of this specific file within the vector store.
    Options:
    pendingin_progresscompletedfailedcancellederror
  • last_error
    last_error
    Type
    object
    Required or Optional
    optional
    An object containing details of the last processing error for this file.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    The identifier of the containing vector store.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    The timestamp indicating when the file was added to the vector store.
  • version
    version
    Type
    integer
    Required or Optional
    optional
    The version of the file within the vector store.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    The storage size used by the file's indexed data in bytes.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

List Vector Store Files

GET/v1/vector_stores/{vector_store_identifier}/files

Retrieves a paginated list of all files within a specific vector store.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store to list files from.

Query Parameters

  • limit
    limit
    Type
    integer
    Required or Optional
    optional
    The maximum number of items to return in the list.
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    The number of items to skip before starting the list.

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    The type of the response object.
  • data
    data
    Type
    VectorStoreFile[]
    Required or Optional
    required
    A list containing the vector store file objects.
  • An object containing pagination details for the list.

Delete Vector Store File

DELETE/v1/vector_stores/{vector_store_identifier}/files/{file_id}

Removes a file from a vector store. This will delete all indexed data for the file.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Path Parameter

  • vector_store_identifier
    vector_store_identifier
    Type
    string
    Required or Optional
    required
    Either the unique ID or the name of the vector store containing the file.
  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    The unique identifier of the target file.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    The ID of the file that was removed.
  • deleted
    deleted
    Type
    boolean
    Required or Optional
    required
    A boolean indicating whether the removal was successful.
  • object
    object
    Type
    string
    Required or Optional
    required
    The type of this object.

Vector Store Search

These endpoints allow searching across one or more vector stores.

Search Vector Store Chunks

POST/v1/vector_stores/search

Performs semantic search across text chunks within your vector stores, returning the most relevant passages.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Request Body

  • query
    query
    Type
    string
    Required or Optional
    required
    The search query text.
  • vector_store_identifiers
    vector_store_identifiers
    Type
    string[]
    Required or Optional
    required
    A list of vector store IDs to perform the search across.
  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    The maximum number of top results to return.
  • Conditions used to filter search results based on metadata. Supports complex logical operations with all, any, and none operators.
  • file_ids
    file_ids
    Type
    string[]
    Required or Optional
    optional
    A list of specific file IDs to limit the search to.
  • An object containing additional configuration for the search operation.

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    The type of the response object.
  • A list of the relevant document chunks found.

Search Vector Store Files

POST/v1/vector_stores/files/search

Searches for the most relevant files in your vector stores, with optional chunk-level results for each file.

Authorization

  • Authorization
    Authorization
    Type
    string
    Required or Optional
    required
    Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`

Request Body

  • query
    query
    Type
    string
    Required or Optional
    required
    The search query text.
  • vector_store_identifiers
    vector_store_identifiers
    Type
    string[]
    Required or Optional
    required
    A list of vector store IDs to perform the search across.
  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    The maximum number of top results to return.
  • Conditions used to filter search results based on metadata. Supports complex logical operations with all, any, and none operators.
  • file_ids
    file_ids
    Type
    string[]
    Required or Optional
    optional
    A list of specific file IDs to limit the search to.

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    The type of the response object.
  • A list of the relevant file objects found.
Error Handling
Documentation on error handling with the Mixedbread API. Learn about common status codes, how to handle them, and best practices for error handling.
Embeddings
API reference for Mixedbread's Embeddings endpoint. This documentation covers all essential endpoints to get you started with embeddings.

Last updated: June 11, 2025