API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Vector Stores

List Vector Stores

client.vectorStores.list(VectorStoreListParams { ending_before, limit, sort_by, 2 more } query?, RequestOptionsoptions?): CursorPageByName<VectorStore { id, created_at, embedding_dimensions, 4 more } >

GET/v5/vector-stores

Create Vector Store

client.vectorStores.create(VectorStoreCreateParams { name, dimensions, embedding_config, 2 more } body, RequestOptionsoptions?): VectorStore { id, created_at, embedding_dimensions, 4 more }

POST/v5/vector-stores/create

Get Vector Store

client.vectorStores.retrieve(stringvectorStoreName, RequestOptionsoptions?): VectorStore { id, created_at, embedding_dimensions, 4 more }

GET/v5/vector-stores/{vector_store_name}

Configure Vector Store

client.vectorStores.configure(stringvectorStoreName, VectorStoreConfigureParams { indexed_metadata_fields } body, RequestOptionsoptions?): VectorStore { id, created_at, embedding_dimensions, 4 more }

POST/v5/vector-stores/{vector_store_name}/configure

Drop Vector Store

client.vectorStores.drop(stringvectorStoreName, RequestOptionsoptions?): VectorStoreDropResponse { name }

POST/v5/vector-stores/{vector_store_name}/drop

Upsert Vectors

client.vectorStores.upsert(stringvectorStoreName, VectorStoreUpsertParams { vectors } body, RequestOptionsoptions?): VectorStoreUpsertResponse { failure_count, success_count, failed, succeeded }

POST/v5/vector-stores/{vector_store_name}/upsert

Delete Vectors

client.vectorStores.delete(stringvectorStoreName, VectorStoreDeleteParams { filter, ids } body, RequestOptionsoptions?): VectorStoreDeleteResponse { deleted_count }

POST/v5/vector-stores/{vector_store_name}/delete

Count Vectors

client.vectorStores.count(stringvectorStoreName, VectorStoreCountParams { filter } body?, RequestOptionsoptions?): VectorStoreCountResponse { count }

POST/v5/vector-stores/{vector_store_name}/count

Query Vectors

client.vectorStores.query(stringvectorStoreName, VectorStoreQueryParams { content, filter, include_vectors, 7 more } body, RequestOptionsoptions?): VectorStoreQueryResponse { metadata, vectors }

POST/v5/vector-stores/{vector_store_name}/query

ModelsExpand Collapse

EmbeddingConfig = EmbeddingConfigModelsAPI { model_deployment_id, type } | EmbeddingConfigBase { embedding_model, type }

One of the following:

EmbeddingConfigModelsAPI { model_deployment_id, type }

model_deployment_id: string

The ID of the deployment of the created model in the Models API V3.

type: "models_api"

The type of the embedding configuration.

EmbeddingConfigBase { embedding_model, type }

embedding_model: EmbeddingModelName | (string & {})

The name of the base embedding model to use. Either a known base model (EmbeddingModelName) or, in ray-serve deployments with NATIVE_OPENAI_EMBEDDING_GATEWAY enabled, any model id served by the OpenAI-compatible inference proxy (e.g. ‘nomic-embed-text-v1.5’). For fully custom deployments, use type ‘models_api’ with a model_deployment_id.

One of the following:

EmbeddingModelName = "sentence-transformers/all-MiniLM-L12-v2" | "sentence-transformers/multi-qa-distilbert-cos-v1" | "openai/text-embedding-ada-002" | 8 more

One of the following:

"sentence-transformers/all-MiniLM-L12-v2"

"sentence-transformers/multi-qa-distilbert-cos-v1"

"openai/text-embedding-ada-002"

"openai/text-embedding-3-small"

"openai/text-embedding-3-large"

"embed-english-v3.0"

"embed-english-light-v3.0"

"embed-multilingual-v3.0"

"gemini/text-embedding-005"

"gemini/text-multilingual-embedding-002"

"gemini/gemini-embedding-001"

(string & {})

type?: "base"

The type of the embedding configuration.

EmbeddingConfigBase { embedding_model, type }

embedding_model: EmbeddingModelName | (string & {})

The name of the base embedding model to use. Either a known base model (EmbeddingModelName) or, in ray-serve deployments with NATIVE_OPENAI_EMBEDDING_GATEWAY enabled, any model id served by the OpenAI-compatible inference proxy (e.g. ‘nomic-embed-text-v1.5’). For fully custom deployments, use type ‘models_api’ with a model_deployment_id.

One of the following:

EmbeddingModelName = "sentence-transformers/all-MiniLM-L12-v2" | "sentence-transformers/multi-qa-distilbert-cos-v1" | "openai/text-embedding-ada-002" | 8 more

One of the following:

"sentence-transformers/all-MiniLM-L12-v2"

"sentence-transformers/multi-qa-distilbert-cos-v1"

"openai/text-embedding-ada-002"

"openai/text-embedding-3-small"

"openai/text-embedding-3-large"

"embed-english-v3.0"

"embed-english-light-v3.0"

"embed-multilingual-v3.0"

"gemini/text-embedding-005"

"gemini/text-multilingual-embedding-002"

"gemini/gemini-embedding-001"

(string & {})

type?: "base"

The type of the embedding configuration.

EmbeddingConfigModelsAPI { model_deployment_id, type }

model_deployment_id: string

The ID of the deployment of the created model in the Models API V3.

type: "models_api"

The type of the embedding configuration.

EmbeddingModelName = "sentence-transformers/all-MiniLM-L12-v2" | "sentence-transformers/multi-qa-distilbert-cos-v1" | "openai/text-embedding-ada-002" | 8 more

One of the following:

"sentence-transformers/all-MiniLM-L12-v2"

"sentence-transformers/multi-qa-distilbert-cos-v1"

"openai/text-embedding-ada-002"

"openai/text-embedding-3-small"

"openai/text-embedding-3-large"

"embed-english-v3.0"

"embed-english-light-v3.0"

"embed-multilingual-v3.0"

"gemini/text-embedding-005"

"gemini/text-multilingual-embedding-002"

"gemini/gemini-embedding-001"

TextContent { text, type }

Text content for documents.

text: string

Text content to be embedded

type?: "text"

Content type identifier

VectorStore { id, created_at, embedding_dimensions, 4 more }

Response model for vector store operations.

id: string

The unique identifier of the vector store

created_at: string

Timestamp of creation

formatdate-time

embedding_dimensions: number

Dimensionality of the embedding vectors

name: string

The name of the vector store

updated_at: string

Timestamp of last update

formatdate-time

embedding_config?: EmbeddingConfig

Embedding configuration identifying the model and its type. None for raw-embedding-only stores.

One of the following:

EmbeddingConfigModelsAPI { model_deployment_id, type }

model_deployment_id: string

The ID of the deployment of the created model in the Models API V3.

type: "models_api"

The type of the embedding configuration.

EmbeddingConfigBase { embedding_model, type }

embedding_model: EmbeddingModelName | (string & {})

The name of the base embedding model to use. Either a known base model (EmbeddingModelName) or, in ray-serve deployments with NATIVE_OPENAI_EMBEDDING_GATEWAY enabled, any model id served by the OpenAI-compatible inference proxy (e.g. ‘nomic-embed-text-v1.5’). For fully custom deployments, use type ‘models_api’ with a model_deployment_id.

One of the following:

EmbeddingModelName = "sentence-transformers/all-MiniLM-L12-v2" | "sentence-transformers/multi-qa-distilbert-cos-v1" | "openai/text-embedding-ada-002" | 8 more

One of the following:

"sentence-transformers/all-MiniLM-L12-v2"

"sentence-transformers/multi-qa-distilbert-cos-v1"

"openai/text-embedding-ada-002"

"openai/text-embedding-3-small"

"openai/text-embedding-3-large"

"embed-english-v3.0"

"embed-english-light-v3.0"

"embed-multilingual-v3.0"

"gemini/text-embedding-005"

"gemini/text-multilingual-embedding-002"

"gemini/gemini-embedding-001"

(string & {})

type?: "base"

The type of the embedding configuration.

indexed_metadata_fields?: Record<string, "string" | "number" | "boolean">

Dictionary mapping metadata field names to their types

One of the following:

"string"

"number"

"boolean"

VectorStoreDropResponse { name }

Response for vector store deletion.

name: string

The name of the deleted vector store

VectorStoreUpsertResponse { failure_count, success_count, failed, succeeded }

Response for batch insert/upsert operations.

failure_count: number

Number of failed documents

success_count: number

Number of successfully processed documents

failed?: Array<Failed>

Failed documents with their error messages

id: string

Document ID

error: string

Error message describing why the document failed

succeeded?: Array<string>

IDs of successfully processed documents

VectorStoreDeleteResponse { deleted_count }

Response for delete operation.

deleted_count: number

Number of documents deleted

VectorStoreCountResponse { count }

Response for count operation.

count: number

Number of documents matching the criteria

VectorStoreQueryResponse { metadata, vectors }

Response for query operation.

metadata: Metadata { search_type, total_query_time_ms, embedding_config, 4 more }

Query execution metadata

search_type: string

Type of search performed (semantic, lexical, hybrid)

total_query_time_ms: number

Total end-to-end query execution time in milliseconds

embedding_config?: EmbeddingConfig

Embedding configuration used for query vectorization. None for lexical queries on model-less stores.

One of the following:

EmbeddingConfigModelsAPI { model_deployment_id, type }

model_deployment_id: string

The ID of the deployment of the created model in the Models API V3.

type: "models_api"

The type of the embedding configuration.

EmbeddingConfigBase { embedding_model, type }

embedding_model: EmbeddingModelName | (string & {})

The name of the base embedding model to use. Either a known base model (EmbeddingModelName) or, in ray-serve deployments with NATIVE_OPENAI_EMBEDDING_GATEWAY enabled, any model id served by the OpenAI-compatible inference proxy (e.g. ‘nomic-embed-text-v1.5’). For fully custom deployments, use type ‘models_api’ with a model_deployment_id.

One of the following:

EmbeddingModelName = "sentence-transformers/all-MiniLM-L12-v2" | "sentence-transformers/multi-qa-distilbert-cos-v1" | "openai/text-embedding-ada-002" | 8 more

One of the following:

"sentence-transformers/all-MiniLM-L12-v2"

"sentence-transformers/multi-qa-distilbert-cos-v1"

"openai/text-embedding-ada-002"

"openai/text-embedding-3-small"

"openai/text-embedding-3-large"

"embed-english-v3.0"

"embed-english-light-v3.0"

"embed-multilingual-v3.0"

"gemini/text-embedding-005"

"gemini/text-multilingual-embedding-002"

"gemini/gemini-embedding-001"

(string & {})

type?: "base"

The type of the embedding configuration.

embedding_time_ms?: number

Time spent generating embeddings in milliseconds (None for lexical queries)

index_query_time_ms?: number

Time spent querying the vector index (OpenSearch) in milliseconds

reranking_model?: string

Reranking model used (None if reranking not enabled)

reranking_time_ms?: number

Time spent reranking results in milliseconds (None if reranking not enabled)

vectors: Array<Vector>

Array of matching documents

id: string

Document ID

score: number

Similarity score indicating relevance

content?: TextContent { text, type }

Text content for documents.

text: string

Text content to be embedded

type?: "text"

Content type identifier

metadata?: Record<string, unknown>

Key-value metadata

vector?: Array<number>

Embedding vector (if requested)

Vector StoresVectors

List Vectors

client.vectorStores.vectors.list(stringvectorStoreName, VectorListParams { cursor, ending_before, filter, 5 more } query?, RequestOptionsoptions?): CursorPageVectors<VectorDocument { id, content, metadata, vector } >

GET/v5/vector-stores/{vector_store_name}/vectors

Get Vector

client.vectorStores.vectors.retrieve(stringvectorID, VectorRetrieveParams { vector_store_name, include_vectors } params, RequestOptionsoptions?): VectorDocument { id, content, metadata, vector }

GET/v5/vector-stores/{vector_store_name}/vectors/{vector_id}

ModelsExpand Collapse

VectorDocument { id, content, metadata, vector }

A document returned from direct lookups (get/list operations).

id: string

Document ID

content?: TextContent { text, type }

Text content for documents.

text: string

Text content to be embedded

type?: "text"

Content type identifier

metadata?: Record<string, unknown>

Key-value metadata

vector?: Array<number>

Embedding vector (if requested)