Mixedbread

Vector Stores

API reference for managing and searching Mixedbread Vector Stores. Covers creating, retrieving, updating, listing, deleting, searching, and performing question answering with vector stores and their associated files.

Create Vector Store

POST/v1/vector_stores

Creates a new, empty vector store. You can add files to it using the vector store files endpoints.

    Request Body

  • name
    name
    Type
    string
    Required or Optional
    optional
    Description

    The name of the vector store.

  • description
    description
    Type
    string
    Required or Optional
    optional
    Description

    A detailed description of the vector store's purpose and contents.

  • expires_after
    expires_after
    Type
    object
    Required or Optional
    optional
    Description

    An expiration policy for the vector store. If not set, the vector store never expires.

  • anchor
    anchor
    Type
    string
    Required or Optional
    optional
    Description

    Anchor date for the expiration policy. Currently only last_active_at is supported.

    • Options: last_active_at
  • days
    days
    Type
    integer
    Required or Optional
    optional
    Description

    Number of days after the anchor date that the vector store expires.

  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description

    A set of key-value pairs to store with the vector store. Useful for storing additional information. Keys can be up to 64 characters long and values can be up to 512 characters long.

  • file_ids
    file_ids
    Type
    string[]
    Required or Optional
    optional
    Description

    An optional list of File IDs that should be added to the vector store upon creation.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    Unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    Description
    Name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    Description
    Detailed description of the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with the vector store.
  • file_counts
    file_counts
    Type
    object
    Required or Optional
    required
    Description

    Counts of files in different processing states within the store.

  • in_progress
    in_progress
    Type
    integer
    Required or Optional
    optional
    Description
    Number of files currently being processed.
  • cancelled
    cancelled
    Type
    integer
    Required or Optional
    optional
    Description
    Number of files whose processing was cancelled.
  • completed
    completed
    Type
    integer
    Required or Optional
    optional
    Description
    Number of successfully processed files.
  • failed
    failed
    Type
    integer
    Required or Optional
    optional
    Description
    Number of files that failed processing.
  • total
    total
    Type
    integer
    Required or Optional
    optional
    Description
    Total number of files associated with the store.

  • expires_after
    expires_after
    Type
    object
    Required or Optional
    optional
    Description

    The expiration policy for the vector store.

  • anchor
    anchor
    Type
    string
    Required or Optional
    optional
    Description

    Anchor date for the expiration policy.

    • Options: last_active_at
  • days
    days
    Type
    integer
    Required or Optional
    optional
    Description

    Number of days after the anchor date that the vector store expires.

  • status
    status
    Type
    string
    Required or Optional
    required
    Description
    Current status of the vector store.
    • Options: expired, in_progress, completed
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when the vector store was created.
  • updated_at
    updated_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when the vector store was last updated.
  • last_active_at
    last_active_at
    Type
    string
    Required or Optional
    optional
    Description
    Timestamp when the vector store was last used.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    Description
    Total storage usage in bytes.
  • expires_at
    expires_at
    Type
    string
    Required or Optional
    optional
    Description
    Timestamp when the vector store will expire, if applicable.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store".

Retrieve Vector Store

GET/v1/vector_stores/{vector_store_id}

Retrieves the details of an existing vector store.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The unique identifier of the vector store to retrieve.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    Unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    Description
    Name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    Description
    Detailed description of the vector store.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with the vector store.
  • file_counts
    file_counts
    Type
    object
    Required or Optional
    required
    Description
    Counts of files in different processing states.
  • expires_after
    expires_after
    Type
    object
    Required or Optional
    optional
    Description
    The expiration policy for the vector store.
  • status
    status
    Type
    string
    Required or Optional
    required
    Description
    Current status of the vector store.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when created.
  • updated_at
    updated_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when last updated.
  • last_active_at
    last_active_at
    Type
    string
    Required or Optional
    optional
    Description
    Timestamp when last used.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    Description
    Total storage usage in bytes.
  • expires_at
    expires_at
    Type
    string
    Required or Optional
    optional
    Description
    Timestamp when it will expire.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store".

Update Vector Store

PUT/v1/vector_stores/{vector_store_id}

Updates the specified vector store.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The unique identifier of the vector store to update.

    • Request Body

  • name
    name
    Type
    string
    Required or Optional
    optional
    Description

    The new name for the vector store.

  • description
    description
    Type
    string
    Required or Optional
    optional
    Description

    The new description for the vector store.

  • expires_after
    expires_after
    Type
    object
    Required or Optional
    optional
    Description

    The new expiration policy for the vector store. Setting to null removes the expiration policy.

  • anchor
    anchor
    Type
    string
    Required or Optional
    optional
    Description

    Anchor date for the expiration policy.

    • Options: last_active_at
  • days
    days
    Type
    integer
    Required or Optional
    optional
    Description

    Number of days after the anchor date that the vector store expires.

  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description

    The new set of key-value pairs to store with the vector store. Existing metadata will be replaced. To remove all metadata, pass an empty object {}.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    Unique identifier for the vector store.
  • name
    name
    Type
    string
    Required or Optional
    required
    Description
    Updated name of the vector store.
  • description
    description
    Type
    string
    Required or Optional
    optional
    Description
    Updated description of the vector store.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store".

List Vector Stores

GET/v1/vector_stores

Retrieves a list of vector stores associated with your account, supporting pagination.

    Query Parameters

  • limit
    limit
    Type
    integer
    Required or Optional
    optional
    Description

    The maximum number of vector stores to return in the list.

    • Default: 20, Max: 100
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    Description

    The number of vector stores to skip before starting to collect the result set.

    • Default: 0

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "list".
  • data
    data
    Type
    VectorStore[]
    Required or Optional
    required
    Description
    A list of vector store objects.
  • pagination
    pagination
    Type
    object
    Required or Optional
    required
    Description

    Pagination information.

  • total
    total
    Type
    integer
    Required or Optional
    optional
    Description
    Total number of vector stores available.
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    Description
    The offset used for this page of results.

Delete Vector Store

DELETE/v1/vector_stores/{vector_store_id}

Deletes the specified vector store and all associated files and data. This action cannot be undone.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The unique identifier of the vector store to delete.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    The ID of the deleted vector store.
  • deleted
    deleted
    Type
    boolean
    Required or Optional
    required
    Description
    Indicates if the deletion was successful.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store".

Vector Store Files

These endpoints manage files within a specific vector store.

Create Vector Store File

POST/v1/vector_stores/{vector_store_id}/files

Adds a file (previously uploaded via the Files API) to a specific vector store for indexing and searching. The file content will be parsed, chunked, and embedded asynchronously.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the vector store to add the file to.

    • Request Body

  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the file (obtained from the Files API) to add to the vector store.

  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description

    Optional metadata to associate specifically with this file within the vector store. This overrides any file-level metadata for search purposes within this store.

  • experimental
    experimental
    Type
    object
    Required or Optional
    optional
    Description

    Experimental options for file processing.

  • parsing_strategy
    parsing_strategy
    Type
    string
    Required or Optional
    optional
    Description

    Strategy for parsing the file content. Defaults may apply.

    • Options: fast, high_quality
  • contextualization
    contextualization
    Type
    boolean
    Required or Optional
    optional
    Description

    Whether to apply contextualization during processing. Defaults may apply.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    Unique identifier for the file within the vector store context.
  • filename
    filename
    Type
    string
    Required or Optional
    optional
    Description
    Name of the associated file.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with this file in the vector store.
  • status
    status
    Type
    string
    Required or Optional
    required
    Description
    Current processing status of the file.
    • Options: pending, in_progress, completed, failed, cancelled, error
  • last_error
    last_error
    Type
    object
    Required or Optional
    optional
    Description
    Details of the last error if processing failed.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description
    ID of the containing vector store.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when the file was added to the vector store.
  • version
    version
    Type
    integer
    Required or Optional
    optional
    Description
    Version number of the file when added.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    Description
    Storage usage in bytes for this file's indexed data.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store.file".

Retrieve Vector Store File

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

Retrieves the details and status of a specific file within a vector store.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the vector store containing the file.

  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the file to retrieve (this is the original File ID).

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    Unique identifier for the file within the vector store context.
  • filename
    filename
    Type
    string
    Required or Optional
    optional
    Description
    Name of the associated file.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with this file in the vector store.
  • status
    status
    Type
    string
    Required or Optional
    required
    Description
    Current processing status.
  • last_error
    last_error
    Type
    object
    Required or Optional
    optional
    Description
    Details of the last error if processing failed.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description
    ID of the containing vector store.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when the file was added.
  • version
    version
    Type
    integer
    Required or Optional
    optional
    Description
    Version number.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    Description
    Storage usage.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store.file".

List Vector Store Files

GET/v1/vector_stores/{vector_store_id}/files

Retrieves a list of files associated with a specific vector store, supporting pagination.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the vector store whose files are to be listed.

    • Query Parameters

  • limit
    limit
    Type
    integer
    Required or Optional
    optional
    Description

    Maximum number of files to return.

    • Default: 20, Max: 100
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    Description

    Number of files to skip.

    • Default: 0

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "list".
  • data
    data
    Type
    VectorStoreFile[]
    Required or Optional
    required
    Description
    A list of vector store file objects.
  • pagination
    pagination
    Type
    object
    Required or Optional
    required
    Description

    Pagination information.

  • total
    total
    Type
    integer
    Required or Optional
    optional
    Description
    Total number of files in the vector store.
  • offset
    offset
    Type
    integer
    Required or Optional
    optional
    Description
    The offset used for this page.

Delete Vector Store File

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

Removes a specific file from a vector store. This deletes the indexed data associated with the file within this store but does not delete the original file from the Files API.

    Path Parameters

  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the vector store containing the file.

  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    Description

    The ID of the file to remove from the vector store.

Response Body

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    The ID of the file that was removed.
  • deleted
    deleted
    Type
    boolean
    Required or Optional
    required
    Description
    Indicates if the removal was successful.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store.file".

These endpoints allow searching across one or more vector stores.

Search Vector Store Chunks

POST/v1/vector_stores/search

Performs a semantic search across indexed chunks within one or more specified vector stores. Returns the most relevant chunks based on the query.

    Request Body

  • query
    query
    Type
    string
    Required or Optional
    required
    Description

    The text query to search for.

  • vector_store_ids
    vector_store_ids
    Type
    string[]
    Required or Optional
    required
    Description

    A list of vector store IDs to search within.

  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    Description

    The maximum number of relevant chunks to return.

    • Default: 10
  • filters
    filters
    Type
    object | object[]
    Required or Optional
    optional
    Description

    Optional filter conditions to apply to the search. Can be a single filter/condition or an array. Supports nested all (AND), any (OR), none (NOT) logical operators and conditions on metadata fields (key, operator, value). Operators: eq, not_eq, gt, gte, lt, lte, in, not_in, like, not_like.

  • search_options
    search_options
    Type
    object
    Required or Optional
    optional
    Description

    Additional options to configure the chunk search behavior.

  • score_threshold
    score_threshold
    Type
    number
    Required or Optional
    optional
    Description
    Minimum similarity score for chunks to be included in the results.
  • rewrite_query
    rewrite_query
    Type
    boolean
    Required or Optional
    optional
    Description
    Whether to internally rewrite the query for potentially better results.
  • return_metadata
    return_metadata
    Type
    boolean
    Required or Optional
    optional
    Description
    Whether to include file metadata in the response chunks.
    • Default: true

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "list".
  • data
    data
    Type
    ScoredVectorStoreChunk[]
    Required or Optional
    required
    Description

    A list of the most relevant chunks found, ordered by relevance score.

  • position
    position
    Type
    integer
    Required or Optional
    required
    Description
    Position index of the chunk within its original file.
  • value
    value
    Type
    string | object
    Required or Optional
    optional
    Description
    Original value/content representation of the chunk (may vary based on source).
  • content
    content
    Type
    string
    Required or Optional
    optional
    Description
    The textual content of the chunk.
  • score
    score
    Type
    number
    Required or Optional
    required
    Description
    The relevance score of the chunk to the query (higher is more relevant).
  • file_id
    file_id
    Type
    string
    Required or Optional
    required
    Description
    ID of the file this chunk belongs to.
  • filename
    filename
    Type
    string
    Required or Optional
    required
    Description
    Filename of the file this chunk belongs to.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description
    ID of the vector store this chunk belongs to.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with the file (if return_metadata was true).

Search Vector Store Files

POST/v1/vector_stores/files/search

Performs a semantic search across entire files within one or more specified vector stores. Returns the most relevant files based on the query, optionally including top matching chunks within those files.

    Request Body

  • query
    query
    Type
    string
    Required or Optional
    required
    Description

    The text query to search for.

  • vector_store_ids
    vector_store_ids
    Type
    string[]
    Required or Optional
    required
    Description

    A list of vector store IDs to search within.

  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    Description

    The maximum number of relevant files to return.

    • Default: 10
  • filters
    filters
    Type
    object | object[]
    Required or Optional
    optional
    Description

    Optional filter conditions to apply to the search (similar structure to chunk search filters).

  • search_options
    search_options
    Type
    object
    Required or Optional
    optional
    Description

    Additional options to configure the file search behavior.

  • score_threshold
    score_threshold
    Type
    number
    Required or Optional
    optional
    Description
    Minimum similarity score for files to be included.
  • rewrite_query
    rewrite_query
    Type
    boolean
    Required or Optional
    optional
    Description
    Whether to internally rewrite the query.
  • return_metadata
    return_metadata
    Type
    boolean
    Required or Optional
    optional
    Description
    Whether to include file metadata in the response.
    • Default: true
  • return_chunks
    return_chunks
    Type
    boolean
    Required or Optional
    optional
    Description
    Whether to return the top matching chunks within each relevant file.
    • Default: false
  • chunks_per_file
    chunks_per_file
    Type
    integer
    Required or Optional
    optional
    Description
    If return_chunks is true, the maximum number of chunks to return per file.
    • Default: 3

Response Body

  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "list".
  • data
    data
    Type
    ScoredVectorStoreFile[]
    Required or Optional
    required
    Description

    A list of the most relevant files found, ordered by relevance score.

  • id
    id
    Type
    string
    Required or Optional
    required
    Description
    ID of the file.
  • filename
    filename
    Type
    string
    Required or Optional
    optional
    Description
    Name of the file.
  • metadata
    metadata
    Type
    object
    Required or Optional
    optional
    Description
    Metadata associated with the file (if return_metadata was true).
  • status
    status
    Type
    string
    Required or Optional
    optional
    Description
    Processing status of the file.
  • last_error
    last_error
    Type
    object
    Required or Optional
    optional
    Description
    Last error message if processing failed.
  • vector_store_id
    vector_store_id
    Type
    string
    Required or Optional
    required
    Description
    ID of the vector store this file belongs to.
  • created_at
    created_at
    Type
    string
    Required or Optional
    required
    Description
    Timestamp when the file was added to the store.
  • version
    version
    Type
    integer
    Required or Optional
    optional
    Description
    Version number of the file.
  • usage_bytes
    usage_bytes
    Type
    integer
    Required or Optional
    optional
    Description
    Storage usage in bytes.
  • object
    object
    Type
    string
    Required or Optional
    required
    Description
    Always "vector_store.file".
  • score
    score
    Type
    number
    Required or Optional
    required
    Description
    The relevance score of the file to the query.

  • chunks
    chunks
    Type
    ScoredVectorStoreChunk[]
    Required or Optional
    optional
    Description

    A list of the top matching chunks within this file (if return_chunks was true). Null otherwise. Chunks have the same structure as in the chunk search response.

Question Answering

POST/v1/vector_stores/question-answering

Answers a question based on the content within specified vector stores. It performs a search to find relevant context and then generates an answer, optionally citing sources.

    Request Body

  • query
    query
    Type
    string
    Required or Optional
    required
    Description

    The question to answer.

  • vector_store_ids
    vector_store_ids
    Type
    string[]
    Required or Optional
    required
    Description

    A list of vector store IDs to use as the knowledge base.

  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    Description

    The maximum number of relevant files/chunks to consider for context.

    • Default: 10
  • filters
    filters
    Type
    object | object[]
    Required or Optional
    optional
    Description

    Optional filter conditions to apply to the context retrieval search.

  • search_options
    search_options
    Type
    object
    Required or Optional
    optional
    Description

    Options to configure the underlying file search used for context retrieval (structure matches VectorStoreFileSearchOptions).

  • score_threshold
    score_threshold
    Type
    number
    Required or Optional
    optional
    Description
  • rewrite_query
    rewrite_query
    Type
    boolean
    Required or Optional
    optional
    Description
  • return_metadata
    return_metadata
    Type
    boolean
    Required or Optional
    optional
    Description
  • return_chunks
    return_chunks
    Type
    boolean
    Required or Optional
    optional
    Description
  • chunks_per_file
    chunks_per_file
    Type
    integer
    Required or Optional
    optional
    Description
  • stream
    stream
    Type
    boolean
    Required or Optional
    optional
    Description

    Whether to stream the answer back as it's generated.

    • Default: false
  • qa_options
    qa_options
    Type
    object
    Required or Optional
    optional
    Description

    Options specific to the question-answering process.

  • cite
    cite
    Type
    boolean
    Required or Optional
    optional
    Description

    Whether to include citations in the generated answer, linking back to the source chunks/files.

    • Default: false

Response Body

  • answer
    answer
    Type
    string
    Required or Optional
    optional
    Description
    The generated answer to the query. Structure might differ for streaming responses.
  • citations
    citations
    Type
    object[]
    Required or Optional
    optional
    Description
    An array of citation objects if cite was true.

Last updated on

Status Codes

Reference for API response status codes and error handling. Learn what each code means, how to interpret error responses, and best practices for implementing robust error handling.

Embeddings

API reference for Mixedbread's Embeddings endpoint. This documentation covers the request and response structure, supported models, and usage examples for generating embeddings using the Mixedbread API.