OpenAI API (unofficial showcase)
POST/vector_stores/{vector_store_id}/file_batches

Create a vector store file batch

Creates a batch to attach files to a vector store for processing. Provide file_ids or files, and optionally set a shared chunking strategy or shared attributes when using file_ids. Use per-file settings in files when different files need different attributes or chunking strategies.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
vector_store_idstringrequired
The ID of the vector store to add files to.

File batch configuration. Provide file_ids or files; both arrays allow 1 to 2,000 entries.

file_idsarray<string>required
A list of [File](https://developers.openai.com/api/reference/resources/files) IDs that the vector store should use. Useful for tools like `file_search` that can access files. If `attributes` or `chunking_strategy` are provided, they will be applied to all files in the batch. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with `files`.
filesarray<object>optional
A list of objects that each include a `file_id` plus optional `attributes` or `chunking_strategy`. Use this when you need to override metadata for specific files. The global `attributes` or `chunking_strategy` will be ignored and must be specified for each file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with `file_ids`.
chunking_strategyobjectoptional
The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.
attributesobjectoptional
Attributes applied across files provided in `file_ids`. Supports up to 16 key-value pairs.

6 status codes
200Returns the created file batch, including its ID, vector store ID, processing status, creation time, and file counts.
idstringrequired
The identifier, which can be referenced in API endpoints.
objectstringrequired
The object type, which is always `vector_store.file_batch`.
Allowed:vector_store.file_batch
created_atintegerrequired
The Unix timestamp (in seconds) for when the vector store files batch was created.
vector_store_idstringrequired
The ID of the [vector store](https://developers.openai.com/api/reference/resources/vector_stores) that the [File](https://developers.openai.com/api/reference/resources/files) is attached to.
statusstringrequired
The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`.
Allowed:in_progresscompletedcancelledfailed
file_countsobjectrequired
400Returned when the file batch input is invalid, the store has expired, or a file limit would be exceeded.
errorobjectrequired
404Returned when the vector store was not found.
errorobjectrequired
409Returned when the vector store is temporarily unavailable for this change or was modified concurrently.
errorobjectrequired
429Returned when the request rate limit is exceeded.
errorobjectrequired
500Returned when the files could not be attached to the vector store.
errorobjectrequired

Error handling

A 400 is returned when the batch input is invalid, the store has expired, or a file limit would be exceeded; a 404 is returned when the vector store is not found. A 409 indicates the store is temporarily unavailable or was modified concurrently; a 429 indicates the request rate limit was exceeded, and a 500 indicates the files could not be attached. The vector_store_id path parameter must identify the store. Provide at least one of file_ids or files; each array must contain 1 to 2,000 entries, and each object in files must include file_id.