List all vector stores in your account with pagination.

Returns vector stores sorted by creation date (newest first). Each store includes its configuration, embedding model, dimensions, indexed fields, and timestamps.

Create a new vector store for storing and querying document embeddings.

The vector store name must be unique within your account and follow naming conventions (3-63 characters, alphanumeric with hyphens/underscores). Once created, the embedding configuration and dimensions are immutable and cannot be changed. To use a different model, you must create a new vector store.

Embedding Configuration: Provide either embedding_config (for base or custom model deployments) or embedding_model (shorthand for a base model). Dimensions are resolved automatically.

Indexed Fields: Optionally specify metadata fields to index at creation time. Only indexed fields can be used for filtering — indexing is required, not just a performance optimization. Additional indexed fields can be added later using the configure endpoint, but cannot be removed once added. Keep in mind that each indexed field increases write latency and storage overhead, so only index fields you actively filter on.

Retrieve detailed configuration and metadata for a specific vector store.

Returns the store's embedding model, dimensions, indexed metadata field definitions, creation timestamp, and last update timestamp. Use this to verify store settings before performing operations or to display store information in your application.

Update the indexed metadata fields configuration for a vector store.

Only indexed metadata fields can be used for filtering during query, list, and count operations. Non-indexed fields cannot be filtered on.

Field Types: Only STRING, NUMBER, and BOOLEAN fields can be indexed (maximum 20 fields). OBJECT and LIST types are stored but cannot be indexed for filtering purposes.

Adding Fields: New indexed fields can be added at any time. Existing documents containing those fields will have their metadata automatically indexed.

Removing Fields: Indexed fields cannot be removed once added. Each indexed field increases write latency and storage overhead, so only index fields you actively filter on.

Note: The name and embedding_config are immutable after creation.

Permanently delete a vector store and all its contents.

⚠️ WARNING: This is a destructive operation that cannot be undone. All documents, embeddings, metadata, and index configurations will be permanently deleted. Data recovery is not possible after deletion.

Insert new documents or update existing documents in a vector store.

Upsert Behavior: If a document ID already exists, it will be completely replaced with the new content and metadata. The previous document's text, embedding, and all metadata fields are discarded. If the ID does not exist, a new document is created.

Automatic Embedding: Text content is automatically embedded using the vector store's configured embedding model. Embedding generation is handled internally—only the text content needs to be provided.

Batch Operations: This endpoint supports batch operations with partial success handling. If some documents fail (e.g., due to validation errors), others will still be processed. The response includes detailed success/failure counts and error messages.

Metadata: Supports nested metadata with string, number, boolean, object, and array types. Null values are not permitted—omit the field or use an empty string instead.

Count documents in a vector store, optionally filtered by metadata.

Use Cases:

• Monitor vector store size and growth over time
• Preview the number of documents matching a filter before deletion
• Validate data ingestion by comparing expected versus actual document counts
• Analyze document distribution across metadata categories

Filtering: Apply the same metadata filter syntax as delete and list operations. Only indexed fields can be used for filtering. An empty filter counts all documents in the store.

Query documents using similarity search with optional reranking.

Primary endpoint for semantic search, question-answering, and RAG (Retrieval-Augmented Generation) applications. Returns documents ranked by relevance to the query text with similarity scores.

Query Types:

• semantic (default): Approximate nearest-neighbor search using HNSW over cosine similarity of document embeddings. Optimal for question-answering, conceptual search, and finding semantically related content without requiring exact keyword matches.
• lexical: Keyword-based text search (BM25 algorithm). Optimal for exact phrase matching, proper nouns, and scenarios where keyword presence is more important than semantic similarity.
• hybrid: Combines semantic and lexical approaches with weighted scoring. Provides maximum recall by identifying documents matching either semantically or lexically.

Metadata Filtering: Narrow the search scope by applying metadata filters (e.g., search only documents where category: "technical"). Only indexed fields can be used for filtering. Filters are applied before similarity search for optimal efficiency.

Reranking (Advanced): Optionally enhance result quality using a cross-encoder reranking model. The reranker rescores the initial results using a more sophisticated model that evaluates the complete query-document pair (not solely embeddings). This adds 100-500ms latency but significantly improves precision for high-stakes applications.

Reranking Strategy: Set top_k higher than the desired final count (e.g., 50) to retrieve more candidates from the initial search. Then configure rerank_top_n to the desired final count (e.g., 10) to return only the most relevant documents after reranking. This two-stage approach maximizes both recall and precision.

Performance Metrics: The response includes detailed timing breakdowns (embedding generation time, index query time, reranking time) to facilitate search pipeline optimization and latency analysis.

Similarity Scores: Each result includes a score field indicating relevance. Higher scores indicate greater relevance. Score ranges and semantics vary by query type (semantic scores use cosine similarity, lexical scores use BM25, hybrid scores combine both approaches).

List documents in a vector store with cursor-based pagination.

Use Cases: Browse documents, export content, audit stored data, or retrieve documents by metadata without semantic search.

Ordering: Documents are returned in storage order (insertion order), not ranked by similarity. For similarity-based retrieval, use the query endpoint.

Filtering: Apply metadata filters to narrow results to specific subsets (e.g., all documents where category: "research"). Only indexed fields can be used for filtering.

Pagination: Uses cursor-based pagination for efficient traversal of large datasets. Pass the next_cursor from each response to retrieve the next page. A null cursor indicates the end of results.

Embedding Vectors: Setting include_vectors=true includes the full embedding vector arrays in the response. This significantly increases payload size and reduces the maximum page size from 1000 to 100 documents. Enable only when raw vectors are required for external processing.

Retrieve a single document by its unique ID.

Returns the document's full content, metadata, and optionally its embedding vector. Use this endpoint for direct lookups when the exact document ID is known. For content similarity search, use the query endpoint.