Vector stores

Knowledge in OpenAI's vector store API, so the OpenAI SDKs call it unchanged: a knowledge base is a vector_store whose id is its kb_ id, a document a vector_store.file whose id is its File's. OpenAI's names, fields and statuses, with HIPS's additions in a hips member OpenAI's clients ignore; a field the routes do not take is a 400 that names it.

Note

Not switched on in production yet: every path on this page answers 404 route_not_found until it is.

POST/v1/vector_storesnot offered

Create a base: name, file_ids, chunking_strategy, metadata, expires_after, and hips with embedding_model, pool and region.

GET/v1/vector_storesnot offered

OpenAI's list: limit, order, after, before.

GET/v1/vector_stores/{id}not offered

The base.

POST/v1/vector_stores/{id}not offered

Change name, metadata, expires_after or hips.pool; the embedding model and the region never change.

DELETE/v1/vector_stores/{id}not offered

{"id", "object": "vector_store.deleted", "deleted": true}; the base is purged.

POST/v1/vector_stores/{id}/filesnot offered

Add a document: file_id, attributes (up to 16 keys), chunking_strategy.

GET/v1/vector_stores/{id}/filesnot offered

The documents, filtered by status.

GET/v1/vector_stores/{id}/files/{file_id}not offered

A document.

POST/v1/vector_stores/{id}/files/{file_id}not offered

Change a document's attributes.

DELETE/v1/vector_stores/{id}/files/{file_id}not offered

Remove a document from the base; the File is kept.

GET/v1/vector_stores/{id}/files/{file_id}/contentnot offered

The document's extracted text, in pages of 262,144 characters with has_more, next_page and page.

POST/v1/vector_stores/{id}/file_batchesnot offered

Add several documents at once: OpenAI's file batches, ids kbb_....

GET/v1/vector_stores/{id}/file_batches/{batch_id}not offered

A file batch with its counts.

POST/v1/vector_stores/{id}/file_batches/{batch_id}/cancelnot offered

Cancel a file batch: documents not read yet end cancelled.

GET/v1/vector_stores/{id}/file_batches/{batch_id}/filesnot offered

The documents of a file batch.

POST/v1/vector_stores/{id}/searchnot offered

Search the base without a model.

Fig. 1, sheet 17API reference

Who may call

Writes
Creating, changing and deleting a base, adding, changing and removing a document, file batches, and uploading a document's File: a full key, or a person's token with the inference scope of a member who may write. Any other key is a 403 key_scope_denied.
Reads and search
Any key of the workspace, an inference_only key included, and a person's token with the inference scope.
Another workspace's id
404, never 403. Reads, exports and deletes answer in a paused workspace too.

The base

vector_store

00000000000000000000000000000000000000001{2  "id": "kb_...",3  "object": "vector_store",4  "created_at": 1792576800,5  "name": "Product manuals",6  "usage_bytes": 0,7  "file_counts": {"in_progress": 0, "completed": 0, "failed": 0, "cancelled": 0, "total": 0},8  "status": "completed",9  "expires_after": null,10  "expires_at": null,11  "last_active_at": 1792576800,12  "metadata": {},13  "hips": {"embedding_model": "<catalog id>", "pool": "auto", "region": "eu", "chunks": 0, "storage": {"price": null, "monthly_micros": null}}14}

vector_store sample

status is in_progress while a document is being read, else completed. usage_bytes is the stored bytes it is billed for; hips.storage its storage price and monthly amount in micro-dollars, null while no storage price is in effect. A base or a document still being read carries openai-poll-after-ms, when to read it again.

The document

id (the file_ id), object: "vector_store.file", vector_store_id, created_at, usage_bytes, status (in_progress, completed, failed, cancelled), last_error (OpenAI's server_error, unsupported_file or invalid_file, and its message), chunking_strategy, attributes, and hips with stage, progress, delayed, error_code, chunks and tokens (Knowledge lists the stages and codes).

Search

The body: query (a string, or a list of strings), max_num_results, filters (OpenAI's comparison filters eq, ne, gt, gte, lt, lte, in, nin and compound and, or over the documents' attributes), ranking_options (score_threshold, ranker). rewrite_query: true is a 400 unsupported_value: HIPS rewrites no query. A NUL in a query or a filter is a 400 invalid_value.

Search answer

00000000000000000000000000000000000000001{2  "object": "vector_store.search_results.page",3  "search_query": "...",4  "data": [5    {"file_id": "file_...", "filename": "manual.pdf", "score": 0.0, "attributes": {},6     "content": [{"type": "text", "text": "..."}],7     "hips": {"heading": "...", "byte_start": 0, "byte_end": 0, "pages": [1]}}8  ],9  "has_more": false,10  "next_page": null11}

Search answer sample

One base a search. A search is one request of your limits. It is billed as one knowledge_search call once its price is in effect; until then nothing is charged and no cost header is written. Server-Timing names the stages kb-base, kb-embed and kb-search.

Errors

Status	Type	Code	Situation	Retry
400	`invalid_request_error`	`invalid_value`	A value is out of range or malformed: `stop` with more than 16 entries, a `prompt_cache_key` over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both `max_tokens` names with different values	No
400	`invalid_request_error`	`unsupported_value`	`n` other than 1, `stream_options` without `stream`, a message role, part, item or tool type not accepted, a hosted tool that is not served	No
400	`invalid_request_error`	`knowledge_not_available`	A Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yet	No
400	`invalid_request_error`	`limit_reached`	A file or knowledge base past a limit the message names. Knowledge is not switched on in production yet	No
400	`invalid_request_error`	`region_unavailable`	A knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yet	No
402	`insufficient_credit`	`insufficient_credit`	The balance does not cover the request's maximum cost at the bound quote	After a top-up
403	`permission_error`	`key_scope_denied`	The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than `full` writing a knowledge base's documents	No
404	`not_found_error`	`knowledge_base_not_found`	A knowledge base that is not the workspace's, or that is being deleted. Knowledge is not switched on in production yet	No
404	`not_found_error`	`route_not_found`	Unknown path, among them every `/v1/jobs` path (not built) and Knowledge's paths while Knowledge is switched off	No
429	`rate_limit_error`	`rate_limit_exceeded`	A rate limit; `param` is `requests`, `tokens`, `uploads`, `batches` (batches created per hour) or `knowledge_search`; `Retry-After`	Yes, after `Retry-After`

A document's File that is not the workspace's, or is gone, is a 404 file_not_found; past the ingestion and search limits the 429 names knowledge_ingest or knowledge_search.

Sheet: 17 of 19
Detail: N
Updated: 2026-11-11

1{2 "id": "kb_...",3 "object": "vector_store",4 "created_at": 1792576800,5 "name": "Product manuals",6 "usage_bytes": 0,7 "file_counts": {"in_progress": 0, "completed": 0, "failed": 0, "cancelled": 0, "total": 0},8 "status": "completed",9 "expires_after": null,10 "expires_at": null,11 "last_active_at": 1792576800,12 "metadata": {},13 "hips": {"embedding_model": "<catalog id>", "pool": "auto", "region": "eu", "chunks": 0, "storage": {"price": null, "monthly_micros": null}}14}

1{2 "object": "vector_store.search_results.page",3 "search_query": "...",4 "data": [5 {"file_id": "file_...", "filename": "manual.pdf", "score": 0.0, "attributes": {},6 "content": [{"type": "text", "text": "..."}],7 "hips": {"heading": "...", "byte_start": 0, "byte_end": 0, "pages": [1]}}8 ],9 "has_more": false,10 "next_page": null11}

Status

Type

Code

Situation

Retry

400

invalid_request_error

invalid_value

A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values

400

invalid_request_error

unsupported_value

n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served

400

invalid_request_error

knowledge_not_available

A Knowledge route while Knowledge's prices are not in effect. Knowledge is not switched on in production yet

400

invalid_request_error

limit_reached

A file or knowledge base past a limit the message names. Knowledge is not switched on in production yet

400

invalid_request_error

region_unavailable

A knowledge base in a region whose store does not exist yet. Knowledge is not switched on in production yet

402

insufficient_credit

The balance does not cover the request's maximum cost at the bound quote

After a top-up

403

permission_error

key_scope_denied

The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than full writing a knowledge base's documents

404

not_found_error

knowledge_base_not_found

A knowledge base that is not the workspace's, or that is being deleted. Knowledge is not switched on in production yet

404

not_found_error

route_not_found

Unknown path, among them every /v1/jobs path (not built) and Knowledge's paths while Knowledge is switched off

429

rate_limit_error

rate_limit_exceeded

A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After

Yes, after Retry-After

Who may call

The base

The document

Search

Errors

Related sheets

Who may call

The base

The document

Search

Errors

Related sheets