POST/v1/vector_stores

Vector Stores

Managed RAG indexes. Create a store, attach files (single or batched), watch their ingest status, run queries through file_search inside an Assistants Run, and (later) migrate the whole store to a different embedding model. Wire shape mirrors OpenAI /v1/vector_stores. Cross-tenant access returns 404 (not 403) so customer IDs stay non-enumerable.

Request

HTTP: POST
URL: /v1/vector_stores
Auth: api_key

Try it

# Stores ─────────────────────────────────────────────────────────
# Create
curl https://api.fightclub.pro/v1/vector_stores \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme-handbook","embedding_model":"text-embedding-3-small"}'

# List (paginated by created_at desc)
curl https://api.fightclub.pro/v1/vector_stores \
  -H "Authorization: Bearer $FC_API_KEY"

# Retrieve one
curl https://api.fightclub.pro/v1/vector_stores/vs_abc \
  -H "Authorization: Bearer $FC_API_KEY"

# Update (name and/or metadata)
curl -X PATCH https://api.fightclub.pro/v1/vector_stores/vs_abc \
  -H "Authorization: Bearer $FC_API_KEY" \
  -d '{"metadata":{"owner":"support-team"}}'

# Delete (soft — flips status to deleting; janitor reaps the Weaviate tenant)
curl -X DELETE https://api.fightclub.pro/v1/vector_stores/vs_abc \
  -H "Authorization: Bearer $FC_API_KEY"

# Files ──────────────────────────────────────────────────────────
# Attach a previously uploaded file (idempotent on (store, file))
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/files \
  -H "Authorization: Bearer $FC_API_KEY" \
  -d '{"file_id":"file_xyz"}'

# List files
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/files \
  -H "Authorization: Bearer $FC_API_KEY"

# Retrieve one (poll for status=completed before querying)
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/files/file_xyz \
  -H "Authorization: Bearer $FC_API_KEY"

# Detach
curl -X DELETE https://api.fightclub.pro/v1/vector_stores/vs_abc/files/file_xyz \
  -H "Authorization: Bearer $FC_API_KEY"

# Cancel a still-pending ingest, or retry a failed/cancelled one
curl -X POST https://api.fightclub.pro/v1/vector_stores/vs_abc/files/file_xyz/cancel \
  -H "Authorization: Bearer $FC_API_KEY"
curl -X POST https://api.fightclub.pro/v1/vector_stores/vs_abc/files/file_xyz/retry \
  -H "Authorization: Bearer $FC_API_KEY"

# File batches ───────────────────────────────────────────────────
# Create a batch (≤ 500 file_ids)
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/file_batches \
  -H "Authorization: Bearer $FC_API_KEY" \
  -d '{"file_ids":["file_1","file_2","file_3"]}'

# Retrieve / cancel a batch
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/file_batches/vsfb_xyz \
  -H "Authorization: Bearer $FC_API_KEY"
curl -X POST https://api.fightclub.pro/v1/vector_stores/vs_abc/file_batches/vsfb_xyz/cancel \
  -H "Authorization: Bearer $FC_API_KEY"

# Observability ──────────────────────────────────────────────────
# Query log (cursor pagination via after=…; since=ISO-8601)
curl "https://api.fightclub.pro/v1/vector_stores/vs_abc/queries?limit=50" \
  -H "Authorization: Bearer $FC_API_KEY"

# Aggregated stats (window = 24h | 7d | 30d, default 24h)
curl "https://api.fightclub.pro/v1/vector_stores/vs_abc/stats?window=7d" \
  -H "Authorization: Bearer $FC_API_KEY"

# Embedding-model migrations ─────────────────────────────────────
# Start a migration (background re-embed against cached parses; atomic index swap)
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/migrate \
  -H "Authorization: Bearer $FC_API_KEY" \
  -d '{"embedding_model":"text-embedding-3-large"}'

# List / retrieve / rollback migrations
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/migrations \
  -H "Authorization: Bearer $FC_API_KEY"
curl https://api.fightclub.pro/v1/vector_stores/vs_abc/migrations/mig_xyz \
  -H "Authorization: Bearer $FC_API_KEY"
curl -X POST https://api.fightclub.pro/v1/vector_stores/vs_abc/migrations/mig_xyz/rollback \
  -H "Authorization: Bearer $FC_API_KEY"

Parameters

Name	Type	Description
name*	string	Store display name. Max 256 bytes.
embedding_model*	string	One of: text-embedding-3-small \| text-embedding-3-large \| text-embedding-ada-002 \| embed-english-v3.0 \| embed-multilingual-v3.0 \| voyage-3-large \| voyage-3-lite \| mistral-embed \| text-embedding-004. Fixed at create time, change via POST /v1/vector_stores/{id}/migrate.
dimensions	integer	Optional embedding-dimension override for models that support it. Positive integer.
metadata	object	Free-form JSON metadata. Max 4 KiB serialized.

Response fields

Name	Type	Description
id	string	Store ID (vs_*).
object	string	Always "vector_store".
name	string	Display name.
embedding_model	string	Embedding model in use.
embedding_dimensions	integer \| null	Dimension override if set at create time.
status	string	active \| suspended \| deleting \| deleted.
file_counts	object	{ total } file count.
bytes	integer	Total bytes stored across all attached files.
metadata	object	Free-form metadata.
created_at	integer	Unix timestamp.

Errors

401invalid_api_key, Missing or revoked key.
400invalid_name, name is empty.
400name_too_long, name exceeds 256 bytes.
400invalid_embedding_model, embedding_model not in the supported set.
400invalid_dimensions, dimensions must be a positive integer.
400invalid_metadata, metadata must be a JSON object (not array or primitive).
400metadata_too_large, metadata exceeds 4096 bytes when serialized.
404vector_store_not_found, No such store (also returned for cross-tenant access).
409vector_store_unavailable, Store is in deleting or deleted state.
402vector_store_suspended, Store is suspended for non-payment.
404vector_store_file_not_found, File row not attached to this store.
404file_not_found, Referenced file_id does not belong to you.
409file_not_cancellable, POST .../cancel against a file that is not pending or in_progress.
409file_not_retryable, POST .../retry against a file that is not failed or cancelled.
400invalid_file_ids, file_batches POST: file_ids must be a non-empty array.
400too_many_files, file_batches POST: at most 500 files per batch.
404file_batch_not_found, Unknown batch_id under the given store.
400missing_embedding_model, POST .../migrate without embedding_model.

See the full error reference.

Examples

rag-products →assistants-with-tools →