Skip to main content
POST
Python (SDK)

Authorizations

Authorization
string
header
required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Headers

X-On-Behalf-Of
string

Optional external end-user identifier forwarded by the API gateway.

Body

application/json

Request body for creating a vector store.

name
string

The name of the vector store.

description
string

A description for the vector store. Can be used to describe the vector store's purpose.

file_ids
string[]

A list of File IDs that the vector store should use. Useful for tools like file_search that can access files. At most 500 per request.

Maximum array length: 500
expires_after
object

The expiration policy for a vector store.

chunking_strategy
object

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.

metadata
object

Set of 16 key-value pairs that can be attached to an object. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

embedding_model
string

The embedding model to use. Defaults to the auto-configured model if not specified.

embedding_dimensions
integer

The number of dimensions for the embedding vectors. Only supported for models with flexible dimensions. If not specified, uses the model's default dimensions.

Required range: -9007199254740991 < x <= 9007199254740991
retrieval_mode
enum<string>

Retrieval mode, frozen at creation (cannot be changed later). 'vector' (default): standard vector similarity search. 'graph': GraphRAG — entities and relations are extracted from every chunk at ingest (metered against your usage) and search traverses the knowledge graph.

Available options:
vector,
graph
extraction_model
string

Model used for entity/relation extraction on graph stores (ingest-time triplet extraction and query-entity extraction). Defaults to the auto-configured model, resolved at creation time — same contract as embedding_model. Only valid when retrieval_mode is 'graph'.

max_hops
integer

Graph expansion depth for graph-mode queries (1-4, engine default 2). Only valid for graph stores.

Required range: 1 <= x <= 4

Response

200 - application/json

OK

A vector store is a collection of processed files that can be used by the file_search tool.

id
string
required

The identifier, which can be referenced in API endpoints.

object
any
required

The object type, which is always 'vector_store'.

created_at
integer
required

The Unix timestamp (in seconds) for when the vector store was created.

Required range: -9007199254740991 <= x <= 9007199254740991
name
string | null
required

The name of the vector store.

usage_bytes
integer
required

The total number of bytes used by the files in the vector store.

Required range: -9007199254740991 <= x <= 9007199254740991
embedding_model
string | null
required

The embedding model used for this vector store. Resolved at creation time from the requested or auto model. Null for legacy vector stores.

embedding_dimensions
integer | null
required

The number of dimensions for the embedding vectors in this vector store. Null for legacy vector stores.

Required range: 0 < x <= 9007199254740991
retrieval_mode
enum<string>
required

Retrieval mode, frozen at creation. 'vector': standard vector similarity search. 'graph': GraphRAG — entities and relations are extracted at ingest and queries traverse the knowledge graph. 'hybrid' is reserved.

Available options:
vector,
hybrid,
graph
file_counts
object
required

File processing status counts.

status
enum<string>
required

The status of the vector store. 'expired' means the store has expired, 'in_progress' means files are still being processed, 'completed' indicates that the vector store is ready for use.

Available options:
expired,
in_progress,
completed
last_active_at
integer | null
required

The Unix timestamp (in seconds) for when the vector store was last active.

Required range: -9007199254740991 <= x <= 9007199254740991
metadata
object
required

Set of 16 key-value pairs that can be attached to an object. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.

last_used_at
integer | null
required

The Unix timestamp (in seconds) for when the vector store was last used.

Required range: -9007199254740991 <= x <= 9007199254740991
extraction_model
string | null

The model used for entity/relation extraction on graph stores. Null for non-graph stores.

max_hops
integer | null

Graph expansion depth for graph-mode queries. Null for non-graph stores.

Required range: 1 <= x <= 4
expires_after
object

The expiration policy for a vector store.

expires_at
integer | null

The Unix timestamp (in seconds) for when the vector store will expire.

Required range: -9007199254740991 <= x <= 9007199254740991
description
string | null

A description for the vector store. Can be used to describe the vector store's purpose.