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

Attach a file to a vector store

Creates an attachment between a file and a vector store. Supply the file's file_id and optionally configure chunking_strategy or attach attributes; use file batches for multi-file ingestion. The response includes the attached file's processing status.

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

1 parameter · 3 body fields
vector_store_idstringrequired
The unique identifier of the vector store to attach the file to.

File attachment details, including the required file identifier and optional chunking and attribute settings.

file_idstringrequired
A [File](https://developers.openai.com/api/reference/resources/files) ID that the vector store should use. Useful for tools like `file_search` that can access files. For multi-file ingestion, we recommend [`file_batches`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) to minimize per-vector-store write requests.
chunking_strategyobjectoptional
The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.
attributesobjectoptional
Optional key-value metadata for the file. Supports up to 16 pairs, with keys no longer than 64 characters.

6 status codes
200Returns the vector store file object, including its identifier, processing status, usage, chunking strategy, and attributes.
idstringrequired
The identifier, which can be referenced in API endpoints.
objectstringrequired
The object type, which is always `vector_store.file`.
Allowed:vector_store.file
usage_bytesintegerrequired
The total vector store usage in bytes. Note that this may be different from the original file size.
created_atintegerrequired
The Unix timestamp (in seconds) for when the vector store file 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 file, which can be either `in_progress`, `completed`, `cancelled`, or `failed`. The status `completed` indicates that the vector store file is ready for use.
Allowed:in_progresscompletedcancelledfailed
last_errorobjectrequired
The last error associated with this vector store file. Will be `null` if there are no errors.
chunking_strategyobjectoptional
The strategy used to chunk the file.
attributesobjectoptional
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.
400Returned when the file input is invalid, the vector store has expired, or attaching the file would exceed a file limit.
errorobjectrequired
404Returned when the vector store does not exist.
errorobjectrequired
409Returned when the vector store is temporarily unavailable for the change or was modified concurrently.
errorobjectrequired
429Returned when the request exceeds a rate limit.
errorobjectrequired
500Returned when the file could not be attached to the vector store.
errorobjectrequired

Error handling

A 400 is returned when the file input is invalid, the store has expired, or a file limit would be exceeded. A 404 is returned when the vector store does not exist; a 409 indicates the store is unavailable for the change or was modified concurrently; a 429 indicates a rate limit; and a 500 means the file could not be attached. The vector_store_id path parameter must identify the store, and file_id is required; attributes can contain at most 16 key-value pairs with keys no longer than 64 characters.