vector-stores

Create a vector store

Creates a new vector store for storing file embeddings. Optionally attaches files to the vector store at creation time via file_ids.

post/api/v1/vector_stores

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/vector_stores
  • Auth: HTTP bearer

Request body

descriptionstring nullable

Description of the vector store

embedding_dimensionsinteger

Hadrian Extension: Embedding dimensions (immutable after creation, default: 1536)

embedding_modelstring

Hadrian Extension: Embedding model to use (immutable after creation, default: text-embedding-3-small)

file_idsstring[]

A list of File IDs that the vector store should use (max 500). Files will be attached to the vector store after creation.

metadataobject nullable

Custom metadata (up to 16 key-value pairs, keys max 64 chars, string values max 512 chars)

namestring nullable

Name of the vector store (optional, auto-generated if not provided)

Response

Vector store created

created_atstring date-time required
descriptionstring nullable

Hadrian Extension: Human-readable description

embedding_dimensionsinteger required

Hadrian Extension: Embedding dimensions for this vector store (immutable after creation)

embedding_modelstring required

Hadrian Extension: Embedding model used for this vector store (immutable after creation)

expires_atstring date-time nullable
idstring required

Vector store ID (serialized with vs_ prefix for OpenAI compatibility)

last_active_atstring date-time nullable
metadataobject nullable
namestring required
objectstring

Object type identifier (always "vector_store" for API compatibility)

owner_idstring uuid required

Hadrian Extension: Owner ID for multi-tenancy

owner_type'organization' | 'team' | 'project' | 'user' required

Owner type for collections (organization, team, project, or user)

status'in_progress' | 'completed' | 'expired' required

VectorStore (vector store) status (OpenAI VectorStore compatible)

Indicates whether the vector store is ready for use.

State Transitions

┌─────────────┐     files processed     ┌─────────────┐
│ in_progress │ ───────────────────────▶│  completed  │
└─────────────┘                         └─────────────┘
                                               │
                                               │ expiration policy
                                               │ triggered
                                               ▼
                                        ┌─────────────┐
                                        │   expired   │
                                        └─────────────┘
  • in_progress: At least one file is being processed (chunked/embedded)
  • completed: All files processed successfully, vector store ready for search
  • expired: Vector store expired per expires_after policy (based on last_active_at)
updated_atstring date-time required

Hadrian Extension: Timestamp of last modification

usage_bytesinteger required

Total storage usage in bytes across all files in this vector store.

This represents the sum of chunk text content sizes (not including embedding vectors). It may differ from the sum of original file sizes due to chunking and text extraction. Updated automatically when files are processed.

Example response

{
  "id": "vs_550e8400-e29b-41d4-a716-446655440000"
}

Changes

No recorded changes to this operation across all 16 revisions of this API.