Vector Stores API¶

Index your files once and search them by meaning. A vector store holds the passages of the files attached to it; a search returns the passages closest to a query, with the file they came from and a similarity score. There is no embedding pipeline, chunker or vector database to run — attach a file and search it.

Why Choose the Vector Stores API?¶

Available Endpoints¶

Feature Compatibility¶

A store this server owns and a knowledge base store answer the same endpoints, but not always the same way. Where the two differ, the row says which one it is talking about.

Model Support¶

No request field names a model: a store embeds with the model it was built with, and a search embeds its query with that same one. Which model that is depends on the kind of store.

Any model this deployment serves that produces embeddings is eligible. To shortlist them, call search_models with route=openai_embedding. A model that produces something else is refused with 400, naming it, when a store is created — never silently, and never at search time.

Listing Order¶

Every listing — stores, a store's files, a batch's files — is ordered by the created_at it reports for each object, most recent first; order=asc reverses it. Objects sharing a second are ordered by identifier, so the sequence is stable from one page to the next.

The after and before cursors are positions in that order: after returns the objects that follow the named one, before the page that ends just before it, both in the direction order asks for. Neither restarts the listing from the top when the object it names has since been deleted.

Quick Start¶

import time

from openai import OpenAI

client = OpenAI(base_url="https://your-gateway/v1", api_key="YOUR_API_KEY")

uploaded = client.files.create(file=open("handbook.txt", "rb"), purpose="assistants")
store = client.vector_stores.create(name="handbook", file_ids=[uploaded.id])

# Indexing is asynchronous: wait until the store reports it finished.
deadline = time.monotonic() + 300
while client.vector_stores.retrieve(store.id).status == "in_progress":
    assert time.monotonic() < deadline, "indexing did not finish"
    time.sleep(2)

for result in client.vector_stores.search(
    store.id, query="How much parental leave do I get?"
):
    print(result.score, result.filename, result.content[0].text)

Indexing Is Asynchronous¶

Attaching a file returns immediately with status="in_progress". Poll the file, or the store, until it settles:

The counters summarise the files, so they can trail a file that has just settled — a store still reporting in_progress for a file already completed converges within a moment. Poll the file itself when you need the earliest possible answer.

Indexing is bounded server-wide: attaching many files at once never indexes more than a couple at a time, so a large attach queues rather than being refused. A poll always terminates: a file whose indexing was interrupted and cannot be resumed settles as failed with last_error.code="server_error", and attaching it again indexes it.

Durable Indexing¶

Whether an interruption costs you anything depends on one deployment setting, AWS_SQS_VECTOR_STORE_QUEUE_URL:

Nothing about the API changes: the same fields, the same statuses, the same polling. A file only takes longer to settle. Indexing stays at-least-once and never bills twice — work that already completed is not redone.

Ask your administrator which of the two your deployment runs before designing a client around it.

Supported Files¶

Files must be text: plain text, Markdown, source code, CSV, JSON, XML, YAML and anything else whose bytes decode as UTF-8 and whose content type is not a known binary one — a text file uploaded as application/octet-stream or application/pdf is refused on its content type, before its bytes are read.

A file that is not text settles as status="failed" with last_error.code="unsupported_file". The message names what that store indexes, and — when another kind of store would take the file as it stands — where to send it instead:

This file type cannot be indexed by this vector store. It indexes text only. Provide the content as a text file. A knowledge base store indexes this file type as it stands.

Convert documents to text otherwise — RAG Pipelines shows a document-conversion stage that produces Markdown from PDF and office formats.

A knowledge base store indexes more than text — PDF and office documents as they stand, and media on a Bedrock managed one. Its own refusals list the formats that store accepts.

Chunking¶

A file is split into overlapping passages before it is indexed. Send a chunking_strategy to choose the split:

{
  "type": "static",
  "static": {"max_chunk_size_tokens": 800, "chunk_overlap_tokens": 400}
}

"type": "auto" inherits the store's own strategy — the one given when it was created — which also applies to every file attached without a strategy at all. A store created without one falls back to the server default, which comes from VECTOR_STORE_CHUNK_SIZE_TOKENS.

GET /v1/vector_stores/{id}/files/{file_id}/content returns the passages a file was indexed as, in document order — the fastest way to see what a chunking strategy actually produced.

Searching¶

page = client.vector_stores.search(
    store.id,
    query="parental leave",
    max_num_results=5,
    filters={"key": "department", "type": "eq", "value": "hr"},
    ranking_options={"score_threshold": 0.4},
)

Each result carries file_id, filename, the file's attributes, the matching content, and a score between 0 and 1 where 1 is an exact match. Results are ordered best first, and the page is complete — search is never paginated.

Filters¶

Filters apply to the attributes of the attached file, never to its content. A filter that matches nothing returns an empty page rather than an error, while an ordering operator given a non-numeric value is rejected with 400: store a date as a number (for example 20260115) to compare ranges of it.

Attributes¶

Up to 16 key-value pairs per attached file, with string, number or boolean values. They are returned on the file and on every search result, and are what filters matches against.

Attributes larger than the total budget are rejected with 400, naming the limit. POST /v1/vector_stores/{id}/files/{file_id} replaces the whole set; the new values apply to later searches once the file is completed. Replacing the attributes of a file that is still in_progress is accepted, but the indexing in flight writes the attributes it started with — wait for the file to settle, then replace them.

Expiration¶

{"expires_after": {"anchor": "last_active_at", "days": 7}}

expires_at is last_active_at plus days. Only a search refreshes last_active_at — attaching, reading or updating a store does not — so a store that is written to but never searched still expires. Once past its expiration a store reads back with status="expired" and returns no search result; its indexed content is released and a search never brings it back. Send "expires_after": null on an update to remove the policy.

Knowledge Base Stores¶

A vector store can also be served by an Amazon Bedrock knowledge base you already created. Allowlist it in AWS_BEDROCK_KNOWLEDGE_BASE_IDS and it is addressed as the vector store vs_kb_<knowledgeBaseId> — the knowledge base identifier is ten alphanumeric characters — on every /v1/vector_stores endpoint, and returned by GET /v1/vector_stores next to the stores the server owns.

Amazon Bedrock builds a knowledge base over documents in two ways, and both are served:

They differ in two things a client can see; everything else on this page holds for either.

The knowledge base stays yours. It is addressed, never created and never deleted; the server searches it and manages the documents of its data source. Its name, description, creation time and status are read from the knowledge base itself.

store = client.vector_stores.retrieve("vs_kb_ABCDE12345")

uploaded = client.files.create(file=open("handbook.pdf", "rb"), purpose="assistants")
client.vector_stores.files.create(
    vector_store_id=store.id, file_id=uploaded.id, attributes={"department": "hr"}
)

for result in client.vector_stores.search(
    store.id, query="How much parental leave do I get?", max_num_results=5
):
    print(result.score, result.filename, result.content[0].text)

What Works¶

filters works in full: all eight comparison operators (eq, ne, gt, gte, lt, lte, in, nin) and both combinators (and, or), over any metadata key, with no schema to declare beforehand.

What Is Refused¶

usage_bytes, file_counts, and a file's chunking_strategy and attributes are reported as unknown — zero, or absent — rather than invented: the corpus is yours, and the server does not claim to know what it holds.

A document's created_at is the only time the knowledge base reports for it: the instant it last ingested that document, which for a document ingested once is when it was created. The document listing is ordered on that same value, so a page never reports a time that contradicts its own order.

Identifiers¶

A file you attach keeps its own file-... identifier. A document that was already in the knowledge base — one of the corpus behind it — is reported under an opaque kbdoc_... identifier, and the per-file routes accept it.

A search covers the whole knowledge base, not only the documents attached here, so a result may name a document of a corpus this API never wrote to. Its kbdoc_... identifier still reads back: GET /v1/vector_stores/{id}/files/{file_id} answers for it, wherever in the knowledge base it lives. Removing it is the one thing refused — that corpus is maintained where it comes from.

Document Formats¶

Files are indexed as they stand, with no conversion step:

One file is at most 5 MiB.

A format outside that table is refused when the file is attached — 400, naming the formats this store takes — rather than accepted and then reported as failed. A file that is attached and then fails is one of a format the store does take, so it settles with last_error.code="server_error".

Where the Two Kinds Differ¶

Only two things differ from the client's point of view:

Cost¶

A knowledge base search costs more than a search on a store the server owns, and a knowledge base backed by an always-on vector database bills whether it is queried or not. This is information for choosing between the two, not a recommendation.

What the usage log reports differs per kind, because the retrieval runs inside the knowledge base rather than through an embedding model of the server's:

Everything left unreported is on your AWS bill and readable from AWS Cost Explorer. Full detail in Cost Management.

Limits¶

A file above the size limit is not rejected at request time: it settles as status="failed" with last_error.code="invalid_file", like any other file that cannot be indexed.

Errors¶

Prerequisites¶

Vector stores are stored in your own AWS account, in an Amazon S3 vector bucket you create yourself. Set AWS_S3_VECTORS_BUCKET to its name and AWS_S3_VECTORS_REGION to its Region; the endpoints answer 503 until both a vector bucket and AWS_S3_BUCKET are configured. The gateway's IAM role needs the Vector Stores permissions.

The model that turns text into vectors is VECTOR_STORE_EMBEDDING_MODEL. It is recorded on each store when the store is created, so changing the setting only affects stores created afterwards — existing stores keep answering with the model they were built with.

Indexing survives a server being replaced only when AWS_SQS_VECTOR_STORE_QUEUE_URL names an Amazon SQS queue you created, with the durable indexing permissions on it — see Durable indexing.

Knowledge base stores need none of the above: they need AWS_BEDROCK_KNOWLEDGE_BASE_IDS, the knowledge base permissions, and a knowledge base in the first AWS_BEDROCK_REGIONS entry. They bring their own storage and their own embedding model, and they are listed and served even when no vector bucket is configured.

See Also¶

• Files API — uploading the files you attach.
• RAG Pipelines — using a vector store as the retrieval stage.
• Embeddings API — embedding text yourself instead.
• Configuration — the settings above.
• Cost Management — what indexing and searching cost.