Vector Stores

List vector stores

$ openai vector-stores list

get /vector_stores

Returns a list of vector stores.

Parameters

--after: optional string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
--before: optional string

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
--limit: optional number

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
--order: optional "asc" or "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

Returns

ListVectorStoresResponse: object { data, first_id, has_more, 2 more }
- data: array of VectorStore
  - id: string
    
    The identifier, which can be referenced in API endpoints.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the vector store was created.
  - file_counts: object { cancelled, completed, failed, 2 more }
    - cancelled: number
      
      The number of files that were cancelled.
    - completed: number
      
      The number of files that have been successfully processed.
    - failed: number
      
      The number of files that have failed to process.
    - in_progress: number
      
      The number of files that are currently being processed.
    - total: number
      
      The total number of files.
  - last_active_at: number
    
    The Unix timestamp (in seconds) for when the vector store was last active.
  - metadata: map[string]
    
    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.
  - name: string
    
    The name of the vector store.
  - object: "vector_store"
    
    The object type, which is always vector_store.
  - status: "expired" or "in_progress" or "completed"
    
    The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
    - "expired"
    - "in_progress"
    - "completed"
  - usage_bytes: number
    
    The total number of bytes used by the files in the vector store.
  - expires_after: optional object { anchor, days }
    
    The expiration policy for a vector store.
    - anchor: "last_active_at"
      
      Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - days: number
      
      The number of days after the anchor time that the vector store will expire.
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the vector store will expire.
- first_id: string
- has_more: boolean
- last_id: string
- object: string

Example

openai vector-stores list \
  --api-key 'My API Key'

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "file_counts": {
        "cancelled": 0,
        "completed": 0,
        "failed": 0,
        "in_progress": 0,
        "total": 0
      },
      "last_active_at": 0,
      "metadata": {
        "foo": "string"
      },
      "name": "name",
      "object": "vector_store",
      "status": "expired",
      "usage_bytes": 0,
      "expires_after": {
        "anchor": "last_active_at",
        "days": 1
      },
      "expires_at": 0
    }
  ],
  "first_id": "vs_abc123",
  "has_more": false,
  "last_id": "vs_abc456",
  "object": "list"
}

Create vector store

$ openai vector-stores create

post /vector_stores

Create a vector store.

Parameters

--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.
--description: optional string

A description for the vector store. Can be used to describe the vector store's purpose.
--expires-after: optional object { anchor, days }

The expiration policy for a vector store.
--file-id: optional array of string

A list of File IDs that the vector store should use. Useful for tools like file_search that can access files.
--metadata: optional map[string]

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.
--name: optional string

The name of the vector store.

Returns

vector_store: object { id, created_at, file_counts, 8 more }

A vector store is a collection of processed files can be used by the file_search tool.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that were cancelled.
  - completed: number
    
    The number of files that have been successfully processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- last_active_at: number
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: map[string]
  
  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.
- name: string
  
  The name of the vector store.
- object: "vector_store"
  
  The object type, which is always vector_store.
- status: "expired" or "in_progress" or "completed"
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: number
  
  The total number of bytes used by the files in the vector store.
- expires_after: optional object { anchor, days }
  
  The expiration policy for a vector store.
  - anchor: "last_active_at"
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - days: number
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

openai vector-stores create \
  --api-key 'My API Key'

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Retrieve vector store

$ openai vector-stores retrieve

get /vector_stores/{vector_store_id}

Retrieves a vector store.

Parameters

--vector-store-id: string

The ID of the vector store to retrieve.

Returns

vector_store: object { id, created_at, file_counts, 8 more }

A vector store is a collection of processed files can be used by the file_search tool.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that were cancelled.
  - completed: number
    
    The number of files that have been successfully processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- last_active_at: number
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: map[string]
  
  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.
- name: string
  
  The name of the vector store.
- object: "vector_store"
  
  The object type, which is always vector_store.
- status: "expired" or "in_progress" or "completed"
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: number
  
  The total number of bytes used by the files in the vector store.
- expires_after: optional object { anchor, days }
  
  The expiration policy for a vector store.
  - anchor: "last_active_at"
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - days: number
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

openai vector-stores retrieve \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Modify vector store

$ openai vector-stores update

post /vector_stores/{vector_store_id}

Modifies a vector store.

Parameters

--vector-store-id: string

The ID of the vector store to modify.
--expires-after: optional object { anchor, days }

The expiration policy for a vector store.
--metadata: optional map[string]

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.
--name: optional string

The name of the vector store.

Returns

vector_store: object { id, created_at, file_counts, 8 more }

A vector store is a collection of processed files can be used by the file_search tool.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that were cancelled.
  - completed: number
    
    The number of files that have been successfully processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- last_active_at: number
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: map[string]
  
  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.
- name: string
  
  The name of the vector store.
- object: "vector_store"
  
  The object type, which is always vector_store.
- status: "expired" or "in_progress" or "completed"
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: number
  
  The total number of bytes used by the files in the vector store.
- expires_after: optional object { anchor, days }
  
  The expiration policy for a vector store.
  - anchor: "last_active_at"
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - days: number
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

openai vector-stores update \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Delete vector store

$ openai vector-stores delete

delete /vector_stores/{vector_store_id}

Delete a vector store.

Parameters

--vector-store-id: string

The ID of the vector store to delete.

Returns

vector_store_deleted: object { id, deleted, object }
- id: string
- deleted: boolean
- object: "vector_store.deleted"

Example

openai vector-stores delete \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id

Response

{
  "id": "id",
  "deleted": true,
  "object": "vector_store.deleted"
}

Search vector store

$ openai vector-stores search

post /vector_stores/{vector_store_id}/search

Search a vector store for relevant chunks based on a query and file attributes filter.

Parameters

--vector-store-id: string

The ID of the vector store to search.
--query: string or array of string

A query string for a search
--filters: optional ComparisonFilter or CompoundFilter

A filter to apply based on file attributes.
--max-num-results: optional number

The maximum number of results to return. This number should be between 1 and 50 inclusive.
--ranking-options: optional object { ranker, score_threshold }

Ranking options for search.
--rewrite-query: optional boolean

Whether to rewrite the natural language query for vector search.

Returns

VectorStoreSearchResultsPage: object { data, has_more, next_page, 2 more }
- data: array of object { attributes, content, file_id, 2 more }
  
  The list of search result items.
  - attributes: map[string or number or boolean]
    
    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.
    - union_member_0: string
    - union_member_1: number
    - union_member_2: boolean
  - content: array of object { text, type }
    
    Content chunks from the file.
    - text: string
      
      The text content returned from search.
    - type: "text"
      
      The type of content.
      - "text"
  - file_id: string
    
    The ID of the vector store file.
  - filename: string
    
    The name of the vector store file.
  - score: number
    
    The similarity score for the result.
- has_more: boolean
  
  Indicates if there are more results to fetch.
- next_page: string
  
  The token for the next page, if any.
- object: "vector_store.search_results.page"
  
  The object type, which is always vector_store.search_results.page
- search_query: array of string

Example

openai vector-stores search \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --query string

Response

{
  "data": [
    {
      "attributes": {
        "foo": "string"
      },
      "content": [
        {
          "text": "text",
          "type": "text"
        }
      ],
      "file_id": "file_id",
      "filename": "filename",
      "score": 0
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "vector_store.search_results.page",
  "search_query": [
    "string"
  ]
}

Domain Types

Auto File Chunking Strategy Param

auto_file_chunking_strategy_param: object { type }

The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
- type: "auto"
  
  Always auto.

File Chunking Strategy

file_chunking_strategy: StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject

The strategy used to chunk the file.
- static_file_chunking_strategy_object: object { static, type }
  - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
    - chunk_overlap_tokens: number
      
      The number of tokens that overlap between chunks. The default value is 400.
      
      Note that the overlap must not exceed half of max_chunk_size_tokens.
    - max_chunk_size_tokens: number
      
      The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
  - type: "static"
    
    Always static.
- other_file_chunking_strategy_object: object { type }
  
  This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
  - type: "other"
    
    Always other.

File Chunking Strategy Param

file_chunking_strategy_param: AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.
- auto_file_chunking_strategy_param: object { type }
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: "auto"
    
    Always auto.
- static_file_chunking_strategy_object_param: object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
    - chunk_overlap_tokens: number
      
      The number of tokens that overlap between chunks. The default value is 400.
      
      Note that the overlap must not exceed half of max_chunk_size_tokens.
    - max_chunk_size_tokens: number
      
      The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
  - type: "static"
    
    Always static.

Other File Chunking Strategy Object

other_file_chunking_strategy_object: object { type }

This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
- type: "other"
  
  Always other.

Static File Chunking Strategy

static_file_chunking_strategy: object { chunk_overlap_tokens, max_chunk_size_tokens }
- chunk_overlap_tokens: number
  
  The number of tokens that overlap between chunks. The default value is 400.
  
  Note that the overlap must not exceed half of max_chunk_size_tokens.
- max_chunk_size_tokens: number
  
  The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.

Static File Chunking Strategy Object

static_file_chunking_strategy_object: object { static, type }
- static: object { chunk_overlap_tokens, max_chunk_size_tokens }
  - chunk_overlap_tokens: number
    
    The number of tokens that overlap between chunks. The default value is 400.
    
    Note that the overlap must not exceed half of max_chunk_size_tokens.
  - max_chunk_size_tokens: number
    
    The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
- type: "static"
  
  Always static.

Static File Chunking Strategy Object Param

static_file_chunking_strategy_object_param: object { static, type }

Customize your own chunking strategy by setting chunk size and chunk overlap.
- static: object { chunk_overlap_tokens, max_chunk_size_tokens }
  - chunk_overlap_tokens: number
    
    The number of tokens that overlap between chunks. The default value is 400.
    
    Note that the overlap must not exceed half of max_chunk_size_tokens.
  - max_chunk_size_tokens: number
    
    The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
- type: "static"
  
  Always static.

Vector Store

vector_store: object { id, created_at, file_counts, 8 more }

A vector store is a collection of processed files can be used by the file_search tool.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that were cancelled.
  - completed: number
    
    The number of files that have been successfully processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- last_active_at: number
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: map[string]
  
  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.
- name: string
  
  The name of the vector store.
- object: "vector_store"
  
  The object type, which is always vector_store.
- status: "expired" or "in_progress" or "completed"
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: number
  
  The total number of bytes used by the files in the vector store.
- expires_after: optional object { anchor, days }
  
  The expiration policy for a vector store.
  - anchor: "last_active_at"
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - days: number
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Vector Store Deleted

vector_store_deleted: object { id, deleted, object }
- id: string
- deleted: boolean
- object: "vector_store.deleted"

Files

List vector store files

$ openai vector-stores:files list

get /vector_stores/{vector_store_id}/files

Returns a list of vector store files.

Parameters

--vector-store-id: string

The ID of the vector store that the files belong to.
--after: optional string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
--before: optional string

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
--filter: optional "in_progress" or "completed" or "failed" or "cancelled"

Filter by file status. One of in_progress, completed, failed, cancelled.
--limit: optional number

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
--order: optional "asc" or "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

Returns

ListVectorStoreFilesResponse: object { data, first_id, has_more, 2 more }
- data: array of VectorStoreFile
  - id: string
    
    The identifier, which can be referenced in API endpoints.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the vector store file was created.
  - last_error: object { code, message }
    
    The last error associated with this vector store file. Will be null if there are no errors.
    - code: "server_error" or "unsupported_file" or "invalid_file"
      
      One of server_error, unsupported_file, or invalid_file.
      - "server_error"
      - "unsupported_file"
      - "invalid_file"
    - message: string
      
      A human-readable description of the error.
  - object: "vector_store.file"
    
    The object type, which is always vector_store.file.
  - status: "in_progress" or "completed" or "cancelled" or "failed"
    
    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.
    - "in_progress"
    - "completed"
    - "cancelled"
    - "failed"
  - usage_bytes: number
    
    The total vector store usage in bytes. Note that this may be different from the original file size.
  - vector_store_id: string
    
    The ID of the vector store that the File is attached to.
  - attributes: optional map[string or number or boolean]
    
    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.
    - union_member_0: string
    - union_member_1: number
    - union_member_2: boolean
  - chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
    
    The strategy used to chunk the file.
    - static_file_chunking_strategy_object: object { static, type }
      - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
        
        chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
        
        max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
      - type: "static"
        
        Always static.
    - other_file_chunking_strategy_object: object { type }
      
      This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
      - type: "other"
        
        Always other.
- first_id: string
- has_more: boolean
- last_id: string
- object: string

Example

openai vector-stores:files list \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "last_error": {
        "code": "server_error",
        "message": "message"
      },
      "object": "vector_store.file",
      "status": "in_progress",
      "usage_bytes": 0,
      "vector_store_id": "vector_store_id",
      "attributes": {
        "foo": "string"
      },
      "chunking_strategy": {
        "static": {
          "chunk_overlap_tokens": 0,
          "max_chunk_size_tokens": 100
        },
        "type": "static"
      }
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Create vector store file

$ openai vector-stores:files create

post /vector_stores/{vector_store_id}/files

Create a vector store file by attaching a File to a vector store.

Parameters

--vector-store-id: string

The ID of the vector store for which to create a File.
--file-id: string

A File 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 to minimize per-vector-store write requests.
--attributes: optional map[string or number or boolean]

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.
--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.

Returns

vector_store_file: object { id, created_at, last_error, 6 more }

A list of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store file was created.
- last_error: object { code, message }
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: "server_error" or "unsupported_file" or "invalid_file"
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: string
    
    A human-readable description of the error.
- object: "vector_store.file"
  
  The object type, which is always vector_store.file.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- usage_bytes: number
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.
- attributes: optional map[string or number or boolean]
  
  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.
  - union_member_0: string
  - union_member_1: number
  - union_member_2: boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - static_file_chunking_strategy_object: object { static, type }
    - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
      - chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
      - max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
    - type: "static"
      
      Always static.
  - other_file_chunking_strategy_object: object { type }
    
    This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
    - type: "other"
      
      Always other.

Example

openai vector-stores:files create \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --file-id file_id

Response

{
  "id": "id",
  "created_at": 0,
  "last_error": {
    "code": "server_error",
    "message": "message"
  },
  "object": "vector_store.file",
  "status": "in_progress",
  "usage_bytes": 0,
  "vector_store_id": "vector_store_id",
  "attributes": {
    "foo": "string"
  },
  "chunking_strategy": {
    "static": {
      "chunk_overlap_tokens": 0,
      "max_chunk_size_tokens": 100
    },
    "type": "static"
  }
}

Update vector store file attributes

$ openai vector-stores:files update

post /vector_stores/{vector_store_id}/files/{file_id}

Update attributes on a vector store file.

Parameters

--vector-store-id: string

The ID of the vector store the file belongs to.
--file-id: string

The ID of the file to update attributes.
--attributes: map[string or number or boolean]

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.

Returns

vector_store_file: object { id, created_at, last_error, 6 more }

A list of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store file was created.
- last_error: object { code, message }
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: "server_error" or "unsupported_file" or "invalid_file"
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: string
    
    A human-readable description of the error.
- object: "vector_store.file"
  
  The object type, which is always vector_store.file.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- usage_bytes: number
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.
- attributes: optional map[string or number or boolean]
  
  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.
  - union_member_0: string
  - union_member_1: number
  - union_member_2: boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - static_file_chunking_strategy_object: object { static, type }
    - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
      - chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
      - max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
    - type: "static"
      
      Always static.
  - other_file_chunking_strategy_object: object { type }
    
    This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
    - type: "other"
      
      Always other.

Example

openai vector-stores:files update \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --file-id file-abc123 \
  --attributes '{foo: string}'

Response

{
  "id": "id",
  "created_at": 0,
  "last_error": {
    "code": "server_error",
    "message": "message"
  },
  "object": "vector_store.file",
  "status": "in_progress",
  "usage_bytes": 0,
  "vector_store_id": "vector_store_id",
  "attributes": {
    "foo": "string"
  },
  "chunking_strategy": {
    "static": {
      "chunk_overlap_tokens": 0,
      "max_chunk_size_tokens": 100
    },
    "type": "static"
  }
}

Retrieve vector store file

$ openai vector-stores:files retrieve

get /vector_stores/{vector_store_id}/files/{file_id}

Retrieves a vector store file.

Parameters

--vector-store-id: string

The ID of the vector store that the file belongs to.
--file-id: string

The ID of the file being retrieved.

Returns

vector_store_file: object { id, created_at, last_error, 6 more }

A list of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store file was created.
- last_error: object { code, message }
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: "server_error" or "unsupported_file" or "invalid_file"
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: string
    
    A human-readable description of the error.
- object: "vector_store.file"
  
  The object type, which is always vector_store.file.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- usage_bytes: number
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.
- attributes: optional map[string or number or boolean]
  
  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.
  - union_member_0: string
  - union_member_1: number
  - union_member_2: boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - static_file_chunking_strategy_object: object { static, type }
    - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
      - chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
      - max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
    - type: "static"
      
      Always static.
  - other_file_chunking_strategy_object: object { type }
    
    This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
    - type: "other"
      
      Always other.

Example

openai vector-stores:files retrieve \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --file-id file-abc123

Response

{
  "id": "id",
  "created_at": 0,
  "last_error": {
    "code": "server_error",
    "message": "message"
  },
  "object": "vector_store.file",
  "status": "in_progress",
  "usage_bytes": 0,
  "vector_store_id": "vector_store_id",
  "attributes": {
    "foo": "string"
  },
  "chunking_strategy": {
    "static": {
      "chunk_overlap_tokens": 0,
      "max_chunk_size_tokens": 100
    },
    "type": "static"
  }
}

Delete vector store file

$ openai vector-stores:files delete

delete /vector_stores/{vector_store_id}/files/{file_id}

Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the delete file endpoint.

Parameters

--vector-store-id: string

The ID of the vector store that the file belongs to.
--file-id: string

The ID of the file to delete.

Returns

vector_store_file_deleted: object { id, deleted, object }
- id: string
- deleted: boolean
- object: "vector_store.file.deleted"

Example

openai vector-stores:files delete \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id \
  --file-id file_id

Response

{
  "id": "id",
  "deleted": true,
  "object": "vector_store.file.deleted"
}

Retrieve vector store file content

$ openai vector-stores:files content

get /vector_stores/{vector_store_id}/files/{file_id}/content

Retrieve the parsed contents of a vector store file.

Parameters

--vector-store-id: string

The ID of the vector store.
--file-id: string

The ID of the file within the vector store.

Returns

VectorStoreFileContentResponse: object { data, has_more, next_page, object }

Represents the parsed content of a vector store file.
- data: array of object { text, type }
  
  Parsed content of the file.
  - text: optional string
    
    The text content
  - type: optional string
    
    The content type (currently only "text")
- has_more: boolean
  
  Indicates if there are more content pages to fetch.
- next_page: string
  
  The token for the next page, if any.
- object: "vector_store.file_content.page"
  
  The object type, which is always vector_store.file_content.page

Example

openai vector-stores:files content \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --file-id file-abc123

Response

{
  "data": [
    {
      "text": "text",
      "type": "type"
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "vector_store.file_content.page"
}

Domain Types

Vector Store File

vector_store_file: object { id, created_at, last_error, 6 more }

A list of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store file was created.
- last_error: object { code, message }
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: "server_error" or "unsupported_file" or "invalid_file"
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: string
    
    A human-readable description of the error.
- object: "vector_store.file"
  
  The object type, which is always vector_store.file.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- usage_bytes: number
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.
- attributes: optional map[string or number or boolean]
  
  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.
  - union_member_0: string
  - union_member_1: number
  - union_member_2: boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - static_file_chunking_strategy_object: object { static, type }
    - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
      - chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
      - max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
    - type: "static"
      
      Always static.
  - other_file_chunking_strategy_object: object { type }
    
    This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
    - type: "other"
      
      Always other.

Vector Store File Deleted

vector_store_file_deleted: object { id, deleted, object }
- id: string
- deleted: boolean
- object: "vector_store.file.deleted"

File Batches

Create vector store file batch

$ openai vector-stores:file-batches create

post /vector_stores/{vector_store_id}/file_batches

Create a vector store file batch.

Parameters

--vector-store-id: string

The ID of the vector store for which to create a File Batch.
--attributes: optional map[string or number or boolean]

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.
--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.
--file-id: optional array of string

A list of File 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.
--file: optional array of object { file_id, attributes, chunking_strategy }

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.

Returns

vector_store_file_batch: object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.

Example

openai vector-stores:file-batches create \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

Retrieve vector store file batch

$ openai vector-stores:file-batches retrieve

get /vector_stores/{vector_store_id}/file_batches/{batch_id}

Retrieves a vector store file batch.

Parameters

--vector-store-id: string

The ID of the vector store that the file batch belongs to.
--batch-id: string

The ID of the file batch being retrieved.

Returns

vector_store_file_batch: object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.

Example

openai vector-stores:file-batches retrieve \
  --api-key 'My API Key' \
  --vector-store-id vs_abc123 \
  --batch-id vsfb_abc123

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

Cancel vector store file batch

$ openai vector-stores:file-batches cancel

post /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.

Parameters

--vector-store-id: string

The ID of the vector store that the file batch belongs to.
--batch-id: string

The ID of the file batch to cancel.

Returns

vector_store_file_batch: object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.

Example

openai vector-stores:file-batches cancel \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id \
  --batch-id batch_id

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

List vector store files in a batch

$ openai vector-stores:file-batches list-files

get /vector_stores/{vector_store_id}/file_batches/{batch_id}/files

Returns a list of vector store files in a batch.

Parameters

--vector-store-id: string

The ID of the vector store that the files belong to.
--batch-id: string

The ID of the file batch that the files belong to.
--after: optional string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
--before: optional string

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
--filter: optional "in_progress" or "completed" or "failed" or "cancelled"

Filter by file status. One of in_progress, completed, failed, cancelled.
--limit: optional number

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
--order: optional "asc" or "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

Returns

ListVectorStoreFilesResponse: object { data, first_id, has_more, 2 more }
- data: array of VectorStoreFile
  - id: string
    
    The identifier, which can be referenced in API endpoints.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the vector store file was created.
  - last_error: object { code, message }
    
    The last error associated with this vector store file. Will be null if there are no errors.
    - code: "server_error" or "unsupported_file" or "invalid_file"
      
      One of server_error, unsupported_file, or invalid_file.
      - "server_error"
      - "unsupported_file"
      - "invalid_file"
    - message: string
      
      A human-readable description of the error.
  - object: "vector_store.file"
    
    The object type, which is always vector_store.file.
  - status: "in_progress" or "completed" or "cancelled" or "failed"
    
    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.
    - "in_progress"
    - "completed"
    - "cancelled"
    - "failed"
  - usage_bytes: number
    
    The total vector store usage in bytes. Note that this may be different from the original file size.
  - vector_store_id: string
    
    The ID of the vector store that the File is attached to.
  - attributes: optional map[string or number or boolean]
    
    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.
    - union_member_0: string
    - union_member_1: number
    - union_member_2: boolean
  - chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
    
    The strategy used to chunk the file.
    - static_file_chunking_strategy_object: object { static, type }
      - static: object { chunk_overlap_tokens, max_chunk_size_tokens }
        
        chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
        
        max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
      - type: "static"
        
        Always static.
    - other_file_chunking_strategy_object: object { type }
      
      This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
      - type: "other"
        
        Always other.
- first_id: string
- has_more: boolean
- last_id: string
- object: string

Example

openai vector-stores:file-batches list-files \
  --api-key 'My API Key' \
  --vector-store-id vector_store_id \
  --batch-id batch_id

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "last_error": {
        "code": "server_error",
        "message": "message"
      },
      "object": "vector_store.file",
      "status": "in_progress",
      "usage_bytes": 0,
      "vector_store_id": "vector_store_id",
      "attributes": {
        "foo": "string"
      },
      "chunking_strategy": {
        "static": {
          "chunk_overlap_tokens": 0,
          "max_chunk_size_tokens": 100
        },
        "type": "static"
      }
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Domain Types

Vector Store File Batch

vector_store_file_batch: object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store that the File is attached to.

cli/resources/vector_stores/index.md +2511 −0 created

1# Vector Stores

3## List vector stores

5`$ openai vector-stores list`

7**get** `/vector_stores`

9Returns a list of vector stores.

11### Parameters

13- `--after: optional string`

15 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

17- `--before: optional string`

19 A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

21- `--limit: optional number`

23 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

25- `--order: optional "asc" or "desc"`

27 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

29### Returns

31- `ListVectorStoresResponse: object { data, first_id, has_more, 2 more }`

33 - `data: array of VectorStore`

35 - `id: string`

37 The identifier, which can be referenced in API endpoints.

39 - `created_at: number`

41 The Unix timestamp (in seconds) for when the vector store was created.

43 - `file_counts: object { cancelled, completed, failed, 2 more }`

45 - `cancelled: number`

47 The number of files that were cancelled.

49 - `completed: number`

51 The number of files that have been successfully processed.

53 - `failed: number`

55 The number of files that have failed to process.

57 - `in_progress: number`

59 The number of files that are currently being processed.

61 - `total: number`

63 The total number of files.

65 - `last_active_at: number`

67 The Unix timestamp (in seconds) for when the vector store was last active.

69 - `metadata: map[string]`

71 Set of 16 key-value pairs that can be attached to an object. This can be

72 useful for storing additional information about the object in a structured

73 format, and querying for objects via API or the dashboard.

75 Keys are strings with a maximum length of 64 characters. Values are strings

76 with a maximum length of 512 characters.

78 - `name: string`

80 The name of the vector store.

82 - `object: "vector_store"`

84 The object type, which is always `vector_store`.

86 - `status: "expired" or "in_progress" or "completed"`

88 The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use.

90 - `"expired"`

92 - `"in_progress"`

94 - `"completed"`

96 - `usage_bytes: number`

98 The total number of bytes used by the files in the vector store.

100 - `expires_after: optional object { anchor, days }`

101

102 The expiration policy for a vector store.

103

104 - `anchor: "last_active_at"`

105

106 Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`.

107

108 - `days: number`

109

110 The number of days after the anchor time that the vector store will expire.

111

112 - `expires_at: optional number`

113

114 The Unix timestamp (in seconds) for when the vector store will expire.

115

116 - `first_id: string`

117

118 - `has_more: boolean`

119

120 - `last_id: string`

121

122 - `object: string`

123

124### Example

125

126```cli

127openai vector-stores list \

128 --api-key 'My API Key'

129```

130

131#### Response

132

133```json

134{

135 "data": [

136 {

137 "id": "id",

138 "created_at": 0,

139 "file_counts": {

140 "cancelled": 0,

141 "completed": 0,

142 "failed": 0,

143 "in_progress": 0,

144 "total": 0

145 },

146 "last_active_at": 0,

147 "metadata": {

148 "foo": "string"

149 },

150 "name": "name",

151 "object": "vector_store",

152 "status": "expired",

153 "usage_bytes": 0,

154 "expires_after": {

155 "anchor": "last_active_at",

156 "days": 1

157 },

158 "expires_at": 0

159 }

160 ],

161 "first_id": "vs_abc123",

162 "has_more": false,

163 "last_id": "vs_abc456",

164 "object": "list"

165}

166```

167

168## Create vector store

169

170`$ openai vector-stores create`

171

172**post** `/vector_stores`

173

174Create a vector store.

175

176### Parameters

177

178- `--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

179

180 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. Only applicable if `file_ids` is non-empty.

181

182- `--description: optional string`

183

184 A description for the vector store. Can be used to describe the vector store's purpose.

185

186- `--expires-after: optional object { anchor, days }`

187

188 The expiration policy for a vector store.

189

190- `--file-id: optional array of string`

191

192 A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that the vector store should use. Useful for tools like `file_search` that can access files.

193

194- `--metadata: optional map[string]`

195

196 Set of 16 key-value pairs that can be attached to an object. This can be

197 useful for storing additional information about the object in a structured

198 format, and querying for objects via API or the dashboard.

199

200 Keys are strings with a maximum length of 64 characters. Values are strings

201 with a maximum length of 512 characters.

202

203- `--name: optional string`

204

205 The name of the vector store.

206

207### Returns

208

209- `vector_store: object { id, created_at, file_counts, 8 more }`

210

211 A vector store is a collection of processed files can be used by the `file_search` tool.

212

213 - `id: string`

214

215 The identifier, which can be referenced in API endpoints.

216

217 - `created_at: number`

218

219 The Unix timestamp (in seconds) for when the vector store was created.

220

221 - `file_counts: object { cancelled, completed, failed, 2 more }`

222

223 - `cancelled: number`

224

225 The number of files that were cancelled.

226

227 - `completed: number`

228

229 The number of files that have been successfully processed.

230

231 - `failed: number`

232

233 The number of files that have failed to process.

234

235 - `in_progress: number`

236

237 The number of files that are currently being processed.

238

239 - `total: number`

240

241 The total number of files.

242

243 - `last_active_at: number`

244

245 The Unix timestamp (in seconds) for when the vector store was last active.

246

247 - `metadata: map[string]`

248

249 Set of 16 key-value pairs that can be attached to an object. This can be

250 useful for storing additional information about the object in a structured

251 format, and querying for objects via API or the dashboard.

252

253 Keys are strings with a maximum length of 64 characters. Values are strings

254 with a maximum length of 512 characters.

255

256 - `name: string`

257

258 The name of the vector store.

259

260 - `object: "vector_store"`

261

262 The object type, which is always `vector_store`.

263

264 - `status: "expired" or "in_progress" or "completed"`

265

266 The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use.

267

268 - `"expired"`

269

270 - `"in_progress"`

271

272 - `"completed"`

273

274 - `usage_bytes: number`

275

276 The total number of bytes used by the files in the vector store.

277

278 - `expires_after: optional object { anchor, days }`

279

280 The expiration policy for a vector store.

281

282 - `anchor: "last_active_at"`

283

284 Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`.

285

286 - `days: number`

287

288 The number of days after the anchor time that the vector store will expire.

289

290 - `expires_at: optional number`

291

292 The Unix timestamp (in seconds) for when the vector store will expire.

293

294### Example

295

296```cli

297openai vector-stores create \

298 --api-key 'My API Key'

299```

300

301#### Response

302

303```json

304{

305 "id": "id",

306 "created_at": 0,

307 "file_counts": {

308 "cancelled": 0,

309 "completed": 0,

310 "failed": 0,

311 "in_progress": 0,

312 "total": 0

313 },

314 "last_active_at": 0,

315 "metadata": {

316 "foo": "string"

317 },

318 "name": "name",

319 "object": "vector_store",

320 "status": "expired",

321 "usage_bytes": 0,

322 "expires_after": {

323 "anchor": "last_active_at",

324 "days": 1

325 },

326 "expires_at": 0

327}

328```

329

330## Retrieve vector store

331

332`$ openai vector-stores retrieve`

333

334**get** `/vector_stores/{vector_store_id}`

335

336Retrieves a vector store.

337

338### Parameters

339

340- `--vector-store-id: string`

341

342 The ID of the vector store to retrieve.

343

344### Returns

345

346- `vector_store: object { id, created_at, file_counts, 8 more }`

347

348 A vector store is a collection of processed files can be used by the `file_search` tool.

349

350 - `id: string`

351

352 The identifier, which can be referenced in API endpoints.

353

354 - `created_at: number`

355

356 The Unix timestamp (in seconds) for when the vector store was created.

357

358 - `file_counts: object { cancelled, completed, failed, 2 more }`

359

360 - `cancelled: number`

361

362 The number of files that were cancelled.

363

364 - `completed: number`

365

366 The number of files that have been successfully processed.

367

368 - `failed: number`

369

370 The number of files that have failed to process.

371

372 - `in_progress: number`

373

374 The number of files that are currently being processed.

375

376 - `total: number`

377

378 The total number of files.

379

380 - `last_active_at: number`

381

382 The Unix timestamp (in seconds) for when the vector store was last active.

383

384 - `metadata: map[string]`

385

386 Set of 16 key-value pairs that can be attached to an object. This can be

387 useful for storing additional information about the object in a structured

388 format, and querying for objects via API or the dashboard.

389

390 Keys are strings with a maximum length of 64 characters. Values are strings

391 with a maximum length of 512 characters.

392

393 - `name: string`

394

395 The name of the vector store.

396

397 - `object: "vector_store"`

398

399 The object type, which is always `vector_store`.

400

401 - `status: "expired" or "in_progress" or "completed"`

402

403 The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use.

404

405 - `"expired"`

406

407 - `"in_progress"`

408

409 - `"completed"`

410

411 - `usage_bytes: number`

412

413 The total number of bytes used by the files in the vector store.

414

415 - `expires_after: optional object { anchor, days }`

416

417 The expiration policy for a vector store.

418

419 - `anchor: "last_active_at"`

420

421 Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`.

422

423 - `days: number`

424

425 The number of days after the anchor time that the vector store will expire.

426

427 - `expires_at: optional number`

428

429 The Unix timestamp (in seconds) for when the vector store will expire.

430

431### Example

432

433```cli

434openai vector-stores retrieve \

435 --api-key 'My API Key' \

436 --vector-store-id vector_store_id

437```

438

439#### Response

440

441```json

442{

443 "id": "id",

444 "created_at": 0,

445 "file_counts": {

446 "cancelled": 0,

447 "completed": 0,

448 "failed": 0,

449 "in_progress": 0,

450 "total": 0

451 },

452 "last_active_at": 0,

453 "metadata": {

454 "foo": "string"

455 },

456 "name": "name",

457 "object": "vector_store",

458 "status": "expired",

459 "usage_bytes": 0,

460 "expires_after": {

461 "anchor": "last_active_at",

462 "days": 1

463 },

464 "expires_at": 0

465}

466```

467

468## Modify vector store

469

470`$ openai vector-stores update`

471

472**post** `/vector_stores/{vector_store_id}`

473

474Modifies a vector store.

475

476### Parameters

477

478- `--vector-store-id: string`

479

480 The ID of the vector store to modify.

481

482- `--expires-after: optional object { anchor, days }`

483

484 The expiration policy for a vector store.

485

486- `--metadata: optional map[string]`

487

488 Set of 16 key-value pairs that can be attached to an object. This can be

489 useful for storing additional information about the object in a structured

490 format, and querying for objects via API or the dashboard.

491

492 Keys are strings with a maximum length of 64 characters. Values are strings

493 with a maximum length of 512 characters.

494

495- `--name: optional string`

496

497 The name of the vector store.

498

499### Returns

500

501- `vector_store: object { id, created_at, file_counts, 8 more }`

502

503 A vector store is a collection of processed files can be used by the `file_search` tool.

504

505 - `id: string`

506

507 The identifier, which can be referenced in API endpoints.

508

509 - `created_at: number`

510

511 The Unix timestamp (in seconds) for when the vector store was created.

512

513 - `file_counts: object { cancelled, completed, failed, 2 more }`

514

515 - `cancelled: number`

516

517 The number of files that were cancelled.

518

519 - `completed: number`

520

521 The number of files that have been successfully processed.

522

523 - `failed: number`

524

525 The number of files that have failed to process.

526

527 - `in_progress: number`

528

529 The number of files that are currently being processed.

530

531 - `total: number`

532

533 The total number of files.

534

535 - `last_active_at: number`

536

537 The Unix timestamp (in seconds) for when the vector store was last active.

538

539 - `metadata: map[string]`

540

541 Set of 16 key-value pairs that can be attached to an object. This can be

542 useful for storing additional information about the object in a structured

543 format, and querying for objects via API or the dashboard.

544

545 Keys are strings with a maximum length of 64 characters. Values are strings

546 with a maximum length of 512 characters.

547

548 - `name: string`

549

550 The name of the vector store.

551

552 - `object: "vector_store"`

553

554 The object type, which is always `vector_store`.

555

556 - `status: "expired" or "in_progress" or "completed"`

557

558 The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use.

559

560 - `"expired"`

561

562 - `"in_progress"`

563

564 - `"completed"`

565

566 - `usage_bytes: number`

567

568 The total number of bytes used by the files in the vector store.

569

570 - `expires_after: optional object { anchor, days }`

571

572 The expiration policy for a vector store.

573

574 - `anchor: "last_active_at"`

575

576 Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`.

577

578 - `days: number`

579

580 The number of days after the anchor time that the vector store will expire.

581

582 - `expires_at: optional number`

583

584 The Unix timestamp (in seconds) for when the vector store will expire.

585

586### Example

587

588```cli

589openai vector-stores update \

590 --api-key 'My API Key' \

591 --vector-store-id vector_store_id

592```

593

594#### Response

595

596```json

597{

598 "id": "id",

599 "created_at": 0,

600 "file_counts": {

601 "cancelled": 0,

602 "completed": 0,

603 "failed": 0,

604 "in_progress": 0,

605 "total": 0

606 },

607 "last_active_at": 0,

608 "metadata": {

609 "foo": "string"

610 },

611 "name": "name",

612 "object": "vector_store",

613 "status": "expired",

614 "usage_bytes": 0,

615 "expires_after": {

616 "anchor": "last_active_at",

617 "days": 1

618 },

619 "expires_at": 0

620}

621```

622

623## Delete vector store

624

625`$ openai vector-stores delete`

626

627**delete** `/vector_stores/{vector_store_id}`

628

629Delete a vector store.

630

631### Parameters

632

633- `--vector-store-id: string`

634

635 The ID of the vector store to delete.

636

637### Returns

638

639- `vector_store_deleted: object { id, deleted, object }`

640

641 - `id: string`

642

643 - `deleted: boolean`

644

645 - `object: "vector_store.deleted"`

646

647### Example

648

649```cli

650openai vector-stores delete \

651 --api-key 'My API Key' \

652 --vector-store-id vector_store_id

653```

654

655#### Response

656

657```json

658{

659 "id": "id",

660 "deleted": true,

661 "object": "vector_store.deleted"

662}

663```

664

665## Search vector store

666

667`$ openai vector-stores search`

668

669**post** `/vector_stores/{vector_store_id}/search`

670

671Search a vector store for relevant chunks based on a query and file attributes filter.

672

673### Parameters

674

675- `--vector-store-id: string`

676

677 The ID of the vector store to search.

678

679- `--query: string or array of string`

680

681 A query string for a search

682

683- `--filters: optional ComparisonFilter or CompoundFilter`

684

685 A filter to apply based on file attributes.

686

687- `--max-num-results: optional number`

688

689 The maximum number of results to return. This number should be between 1 and 50 inclusive.

690

691- `--ranking-options: optional object { ranker, score_threshold }`

692

693 Ranking options for search.

694

695- `--rewrite-query: optional boolean`

696

697 Whether to rewrite the natural language query for vector search.

698

699### Returns

700

701- `VectorStoreSearchResultsPage: object { data, has_more, next_page, 2 more }`

702

703 - `data: array of object { attributes, content, file_id, 2 more }`

704

705 The list of search result items.

706

707 - `attributes: map[string or number or boolean]`

708

709 Set of 16 key-value pairs that can be attached to an object. This can be

710 useful for storing additional information about the object in a structured

711 format, and querying for objects via API or the dashboard. Keys are strings

712 with a maximum length of 64 characters. Values are strings with a maximum

713 length of 512 characters, booleans, or numbers.

714

715 - `union_member_0: string`

716

717 - `union_member_1: number`

718

719 - `union_member_2: boolean`

720

721 - `content: array of object { text, type }`

722

723 Content chunks from the file.

724

725 - `text: string`

726

727 The text content returned from search.

728

729 - `type: "text"`

730

731 The type of content.

732

733 - `"text"`

734

735 - `file_id: string`

736

737 The ID of the vector store file.

738

739 - `filename: string`

740

741 The name of the vector store file.

742

743 - `score: number`

744

745 The similarity score for the result.

746

747 - `has_more: boolean`

748

749 Indicates if there are more results to fetch.

750

751 - `next_page: string`

752

753 The token for the next page, if any.

754

755 - `object: "vector_store.search_results.page"`

756

757 The object type, which is always `vector_store.search_results.page`

758

759 - `search_query: array of string`

760

761### Example

762

763```cli

764openai vector-stores search \

765 --api-key 'My API Key' \

766 --vector-store-id vs_abc123 \

767 --query string

768```

769

770#### Response

771

772```json

773{

774 "data": [

775 {

776 "attributes": {

777 "foo": "string"

778 },

779 "content": [

780 {

781 "text": "text",

782 "type": "text"

783 }

784 ],

785 "file_id": "file_id",

786 "filename": "filename",

787 "score": 0

788 }

789 ],

790 "has_more": true,

791 "next_page": "next_page",

792 "object": "vector_store.search_results.page",

793 "search_query": [

794 "string"

795 ]

796}

797```

798

799## Domain Types

800

801### Auto File Chunking Strategy Param

802

803- `auto_file_chunking_strategy_param: object { type }`

804

805 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

806

807 - `type: "auto"`

808

809 Always `auto`.

810

811### File Chunking Strategy

812

813- `file_chunking_strategy: StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

814

815 The strategy used to chunk the file.

816

817 - `static_file_chunking_strategy_object: object { static, type }`

818

819 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

820

821 - `chunk_overlap_tokens: number`

822

823 The number of tokens that overlap between chunks. The default value is `400`.

824

825 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

826

827 - `max_chunk_size_tokens: number`

828

829 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

830

831 - `type: "static"`

832

833 Always `static`.

834

835 - `other_file_chunking_strategy_object: object { type }`

836

837 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

838

839 - `type: "other"`

840

841 Always `other`.

842

843### File Chunking Strategy Param

844

845- `file_chunking_strategy_param: AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

846

847 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. Only applicable if `file_ids` is non-empty.

848

849 - `auto_file_chunking_strategy_param: object { type }`

850

851 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

852

853 - `type: "auto"`

854

855 Always `auto`.

856

857 - `static_file_chunking_strategy_object_param: object { static, type }`

858

859 Customize your own chunking strategy by setting chunk size and chunk overlap.

860

861 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

862

863 - `chunk_overlap_tokens: number`

864

865 The number of tokens that overlap between chunks. The default value is `400`.

866

867 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

868

869 - `max_chunk_size_tokens: number`

870

871 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

872

873 - `type: "static"`

874

875 Always `static`.

876

877### Other File Chunking Strategy Object

878

879- `other_file_chunking_strategy_object: object { type }`

880

881 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

882

883 - `type: "other"`

884

885 Always `other`.

886

887### Static File Chunking Strategy

888

889- `static_file_chunking_strategy: object { chunk_overlap_tokens, max_chunk_size_tokens }`

890

891 - `chunk_overlap_tokens: number`

892

893 The number of tokens that overlap between chunks. The default value is `400`.

894

895 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

896

897 - `max_chunk_size_tokens: number`

898

899 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

900

901### Static File Chunking Strategy Object

902

903- `static_file_chunking_strategy_object: object { static, type }`

904

905 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

906

907 - `chunk_overlap_tokens: number`

908

909 The number of tokens that overlap between chunks. The default value is `400`.

910

911 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

912

913 - `max_chunk_size_tokens: number`

914

915 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

916

917 - `type: "static"`

918

919 Always `static`.

920

921### Static File Chunking Strategy Object Param

922

923- `static_file_chunking_strategy_object_param: object { static, type }`

924

925 Customize your own chunking strategy by setting chunk size and chunk overlap.

926

927 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

928

929 - `chunk_overlap_tokens: number`

930

931 The number of tokens that overlap between chunks. The default value is `400`.

932

933 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

934

935 - `max_chunk_size_tokens: number`

936

937 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

938

939 - `type: "static"`

940

941 Always `static`.

942

943### Vector Store

944

945- `vector_store: object { id, created_at, file_counts, 8 more }`

946

947 A vector store is a collection of processed files can be used by the `file_search` tool.

948

949 - `id: string`

950

951 The identifier, which can be referenced in API endpoints.

952

953 - `created_at: number`

954

955 The Unix timestamp (in seconds) for when the vector store was created.

956

957 - `file_counts: object { cancelled, completed, failed, 2 more }`

958

959 - `cancelled: number`

960

961 The number of files that were cancelled.

962

963 - `completed: number`

964

965 The number of files that have been successfully processed.

966

967 - `failed: number`

968

969 The number of files that have failed to process.

970

971 - `in_progress: number`

972

973 The number of files that are currently being processed.

974

975 - `total: number`

976

977 The total number of files.

978

979 - `last_active_at: number`

980

981 The Unix timestamp (in seconds) for when the vector store was last active.

982

983 - `metadata: map[string]`

984

985 Set of 16 key-value pairs that can be attached to an object. This can be

986 useful for storing additional information about the object in a structured

987 format, and querying for objects via API or the dashboard.

988

989 Keys are strings with a maximum length of 64 characters. Values are strings

990 with a maximum length of 512 characters.

991

992 - `name: string`

993

994 The name of the vector store.

995

996 - `object: "vector_store"`

997

998 The object type, which is always `vector_store`.

999

1000 - `status: "expired" or "in_progress" or "completed"`

1001

1002 The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use.

1003

1004 - `"expired"`

1005

1006 - `"in_progress"`

1007

1008 - `"completed"`

1009

1010 - `usage_bytes: number`

1011

1012 The total number of bytes used by the files in the vector store.

1013

1014 - `expires_after: optional object { anchor, days }`

1015

1016 The expiration policy for a vector store.

1017

1018 - `anchor: "last_active_at"`

1019

1020 Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`.

1021

1022 - `days: number`

1023

1024 The number of days after the anchor time that the vector store will expire.

1025

1026 - `expires_at: optional number`

1027

1028 The Unix timestamp (in seconds) for when the vector store will expire.

1029

1030### Vector Store Deleted

1031

1032- `vector_store_deleted: object { id, deleted, object }`

1033

1034 - `id: string`

1035

1036 - `deleted: boolean`

1037

1038 - `object: "vector_store.deleted"`

1039

1040# Files

1041

1042## List vector store files

1043

1044`$ openai vector-stores:files list`

1045

1046**get** `/vector_stores/{vector_store_id}/files`

1047

1048Returns a list of vector store files.

1049

1050### Parameters

1051

1052- `--vector-store-id: string`

1053

1054 The ID of the vector store that the files belong to.

1055

1056- `--after: optional string`

1057

1058 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

1059

1060- `--before: optional string`

1061

1062 A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

1063

1064- `--filter: optional "in_progress" or "completed" or "failed" or "cancelled"`

1065

1066 Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.

1067

1068- `--limit: optional number`

1069

1070 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

1071

1072- `--order: optional "asc" or "desc"`

1073

1074 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

1075

1076### Returns

1077

1078- `ListVectorStoreFilesResponse: object { data, first_id, has_more, 2 more }`

1079

1080 - `data: array of VectorStoreFile`

1081

1082 - `id: string`

1083

1084 The identifier, which can be referenced in API endpoints.

1085

1086 - `created_at: number`

1087

1088 The Unix timestamp (in seconds) for when the vector store file was created.

1089

1090 - `last_error: object { code, message }`

1091

1092 The last error associated with this vector store file. Will be `null` if there are no errors.

1093

1094 - `code: "server_error" or "unsupported_file" or "invalid_file"`

1095

1096 One of `server_error`, `unsupported_file`, or `invalid_file`.

1097

1098 - `"server_error"`

1099

1100 - `"unsupported_file"`

1101

1102 - `"invalid_file"`

1103

1104 - `message: string`

1105

1106 A human-readable description of the error.

1107

1108 - `object: "vector_store.file"`

1109

1110 The object type, which is always `vector_store.file`.

1111

1112 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

1113

1114 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.

1115

1116 - `"in_progress"`

1117

1118 - `"completed"`

1119

1120 - `"cancelled"`

1121

1122 - `"failed"`

1123

1124 - `usage_bytes: number`

1125

1126 The total vector store usage in bytes. Note that this may be different from the original file size.

1127

1128 - `vector_store_id: string`

1129

1130 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

1131

1132 - `attributes: optional map[string or number or boolean]`

1133

1134 Set of 16 key-value pairs that can be attached to an object. This can be

1135 useful for storing additional information about the object in a structured

1136 format, and querying for objects via API or the dashboard. Keys are strings

1137 with a maximum length of 64 characters. Values are strings with a maximum

1138 length of 512 characters, booleans, or numbers.

1139

1140 - `union_member_0: string`

1141

1142 - `union_member_1: number`

1143

1144 - `union_member_2: boolean`

1145

1146 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1147

1148 The strategy used to chunk the file.

1149

1150 - `static_file_chunking_strategy_object: object { static, type }`

1151

1152 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

1153

1154 - `chunk_overlap_tokens: number`

1155

1156 The number of tokens that overlap between chunks. The default value is `400`.

1157

1158 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1159

1160 - `max_chunk_size_tokens: number`

1161

1162 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1163

1164 - `type: "static"`

1165

1166 Always `static`.

1167

1168 - `other_file_chunking_strategy_object: object { type }`

1169

1170 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

1171

1172 - `type: "other"`

1173

1174 Always `other`.

1175

1176 - `first_id: string`

1177

1178 - `has_more: boolean`

1179

1180 - `last_id: string`

1181

1182 - `object: string`

1183

1184### Example

1185

1186```cli

1187openai vector-stores:files list \

1188 --api-key 'My API Key' \

1189 --vector-store-id vector_store_id

1190```

1191

1192#### Response

1193

1194```json

1195{

1196 "data": [

1197 {

1198 "id": "id",

1199 "created_at": 0,

1200 "last_error": {

1201 "code": "server_error",

1202 "message": "message"

1203 },

1204 "object": "vector_store.file",

1205 "status": "in_progress",

1206 "usage_bytes": 0,

1207 "vector_store_id": "vector_store_id",

1208 "attributes": {

1209 "foo": "string"

1210 },

1211 "chunking_strategy": {

1212 "static": {

1213 "chunk_overlap_tokens": 0,

1214 "max_chunk_size_tokens": 100

1215 },

1216 "type": "static"

1217 }

1218 }

1219 ],

1220 "first_id": "file-abc123",

1221 "has_more": false,

1222 "last_id": "file-abc456",

1223 "object": "list"

1224}

1225```

1226

1227## Create vector store file

1228

1229`$ openai vector-stores:files create`

1230

1231**post** `/vector_stores/{vector_store_id}/files`

1232

1233Create a vector store file by attaching a [File](https://platform.openai.com/docs/api-reference/files) to a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object).

1234

1235### Parameters

1236

1237- `--vector-store-id: string`

1238

1239 The ID of the vector store for which to create a File.

1240

1241- `--file-id: string`

1242

1243 A [File](https://platform.openai.com/docs/api-reference/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://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch) to minimize per-vector-store write requests.

1244

1245- `--attributes: optional map[string or number or boolean]`

1246

1247 Set of 16 key-value pairs that can be attached to an object. This can be

1248 useful for storing additional information about the object in a structured

1249 format, and querying for objects via API or the dashboard. Keys are strings

1250 with a maximum length of 64 characters. Values are strings with a maximum

1251 length of 512 characters, booleans, or numbers.

1252

1253- `--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

1254

1255 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. Only applicable if `file_ids` is non-empty.

1256

1257### Returns

1258

1259- `vector_store_file: object { id, created_at, last_error, 6 more }`

1260

1261 A list of files attached to a vector store.

1262

1263 - `id: string`

1264

1265 The identifier, which can be referenced in API endpoints.

1266

1267 - `created_at: number`

1268

1269 The Unix timestamp (in seconds) for when the vector store file was created.

1270

1271 - `last_error: object { code, message }`

1272

1273 The last error associated with this vector store file. Will be `null` if there are no errors.

1274

1275 - `code: "server_error" or "unsupported_file" or "invalid_file"`

1276

1277 One of `server_error`, `unsupported_file`, or `invalid_file`.

1278

1279 - `"server_error"`

1280

1281 - `"unsupported_file"`

1282

1283 - `"invalid_file"`

1284

1285 - `message: string`

1286

1287 A human-readable description of the error.

1288

1289 - `object: "vector_store.file"`

1290

1291 The object type, which is always `vector_store.file`.

1292

1293 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

1294

1295 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.

1296

1297 - `"in_progress"`

1298

1299 - `"completed"`

1300

1301 - `"cancelled"`

1302

1303 - `"failed"`

1304

1305 - `usage_bytes: number`

1306

1307 The total vector store usage in bytes. Note that this may be different from the original file size.

1308

1309 - `vector_store_id: string`

1310

1311 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

1312

1313 - `attributes: optional map[string or number or boolean]`

1314

1315 Set of 16 key-value pairs that can be attached to an object. This can be

1316 useful for storing additional information about the object in a structured

1317 format, and querying for objects via API or the dashboard. Keys are strings

1318 with a maximum length of 64 characters. Values are strings with a maximum

1319 length of 512 characters, booleans, or numbers.

1320

1321 - `union_member_0: string`

1322

1323 - `union_member_1: number`

1324

1325 - `union_member_2: boolean`

1326

1327 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1328

1329 The strategy used to chunk the file.

1330

1331 - `static_file_chunking_strategy_object: object { static, type }`

1332

1333 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

1334

1335 - `chunk_overlap_tokens: number`

1336

1337 The number of tokens that overlap between chunks. The default value is `400`.

1338

1339 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1340

1341 - `max_chunk_size_tokens: number`

1342

1343 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1344

1345 - `type: "static"`

1346

1347 Always `static`.

1348

1349 - `other_file_chunking_strategy_object: object { type }`

1350

1351 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

1352

1353 - `type: "other"`

1354

1355 Always `other`.

1356

1357### Example

1358

1359```cli

1360openai vector-stores:files create \

1361 --api-key 'My API Key' \

1362 --vector-store-id vs_abc123 \

1363 --file-id file_id

1364```

1365

1366#### Response

1367

1368```json

1369{

1370 "id": "id",

1371 "created_at": 0,

1372 "last_error": {

1373 "code": "server_error",

1374 "message": "message"

1375 },

1376 "object": "vector_store.file",

1377 "status": "in_progress",

1378 "usage_bytes": 0,

1379 "vector_store_id": "vector_store_id",

1380 "attributes": {

1381 "foo": "string"

1382 },

1383 "chunking_strategy": {

1384 "static": {

1385 "chunk_overlap_tokens": 0,

1386 "max_chunk_size_tokens": 100

1387 },

1388 "type": "static"

1389 }

1390}

1391```

1392

1393## Update vector store file attributes

1394

1395`$ openai vector-stores:files update`

1396

1397**post** `/vector_stores/{vector_store_id}/files/{file_id}`

1398

1399Update attributes on a vector store file.

1400

1401### Parameters

1402

1403- `--vector-store-id: string`

1404

1405 The ID of the vector store the file belongs to.

1406

1407- `--file-id: string`

1408

1409 The ID of the file to update attributes.

1410

1411- `--attributes: map[string or number or boolean]`

1412

1413 Set of 16 key-value pairs that can be attached to an object. This can be

1414 useful for storing additional information about the object in a structured

1415 format, and querying for objects via API or the dashboard. Keys are strings

1416 with a maximum length of 64 characters. Values are strings with a maximum

1417 length of 512 characters, booleans, or numbers.

1418

1419### Returns

1420

1421- `vector_store_file: object { id, created_at, last_error, 6 more }`

1422

1423 A list of files attached to a vector store.

1424

1425 - `id: string`

1426

1427 The identifier, which can be referenced in API endpoints.

1428

1429 - `created_at: number`

1430

1431 The Unix timestamp (in seconds) for when the vector store file was created.

1432

1433 - `last_error: object { code, message }`

1434

1435 The last error associated with this vector store file. Will be `null` if there are no errors.

1436

1437 - `code: "server_error" or "unsupported_file" or "invalid_file"`

1438

1439 One of `server_error`, `unsupported_file`, or `invalid_file`.

1440

1441 - `"server_error"`

1442

1443 - `"unsupported_file"`

1444

1445 - `"invalid_file"`

1446

1447 - `message: string`

1448

1449 A human-readable description of the error.

1450

1451 - `object: "vector_store.file"`

1452

1453 The object type, which is always `vector_store.file`.

1454

1455 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

1456

1457 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.

1458

1459 - `"in_progress"`

1460

1461 - `"completed"`

1462

1463 - `"cancelled"`

1464

1465 - `"failed"`

1466

1467 - `usage_bytes: number`

1468

1469 The total vector store usage in bytes. Note that this may be different from the original file size.

1470

1471 - `vector_store_id: string`

1472

1473 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

1474

1475 - `attributes: optional map[string or number or boolean]`

1476

1477 Set of 16 key-value pairs that can be attached to an object. This can be

1478 useful for storing additional information about the object in a structured

1479 format, and querying for objects via API or the dashboard. Keys are strings

1480 with a maximum length of 64 characters. Values are strings with a maximum

1481 length of 512 characters, booleans, or numbers.

1482

1483 - `union_member_0: string`

1484

1485 - `union_member_1: number`

1486

1487 - `union_member_2: boolean`

1488

1489 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1490

1491 The strategy used to chunk the file.

1492

1493 - `static_file_chunking_strategy_object: object { static, type }`

1494

1495 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

1496

1497 - `chunk_overlap_tokens: number`

1498

1499 The number of tokens that overlap between chunks. The default value is `400`.

1500

1501 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1502

1503 - `max_chunk_size_tokens: number`

1504

1505 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1506

1507 - `type: "static"`

1508

1509 Always `static`.

1510

1511 - `other_file_chunking_strategy_object: object { type }`

1512

1513 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

1514

1515 - `type: "other"`

1516

1517 Always `other`.

1518

1519### Example

1520

1521```cli

1522openai vector-stores:files update \

1523 --api-key 'My API Key' \

1524 --vector-store-id vs_abc123 \

1525 --file-id file-abc123 \

1526 --attributes '{foo: string}'

1527```

1528

1529#### Response

1530

1531```json

1532{

1533 "id": "id",

1534 "created_at": 0,

1535 "last_error": {

1536 "code": "server_error",

1537 "message": "message"

1538 },

1539 "object": "vector_store.file",

1540 "status": "in_progress",

1541 "usage_bytes": 0,

1542 "vector_store_id": "vector_store_id",

1543 "attributes": {

1544 "foo": "string"

1545 },

1546 "chunking_strategy": {

1547 "static": {

1548 "chunk_overlap_tokens": 0,

1549 "max_chunk_size_tokens": 100

1550 },

1551 "type": "static"

1552 }

1553}

1554```

1555

1556## Retrieve vector store file

1557

1558`$ openai vector-stores:files retrieve`

1559

1560**get** `/vector_stores/{vector_store_id}/files/{file_id}`

1561

1562Retrieves a vector store file.

1563

1564### Parameters

1565

1566- `--vector-store-id: string`

1567

1568 The ID of the vector store that the file belongs to.

1569

1570- `--file-id: string`

1571

1572 The ID of the file being retrieved.

1573

1574### Returns

1575

1576- `vector_store_file: object { id, created_at, last_error, 6 more }`

1577

1578 A list of files attached to a vector store.

1579

1580 - `id: string`

1581

1582 The identifier, which can be referenced in API endpoints.

1583

1584 - `created_at: number`

1585

1586 The Unix timestamp (in seconds) for when the vector store file was created.

1587

1588 - `last_error: object { code, message }`

1589

1590 The last error associated with this vector store file. Will be `null` if there are no errors.

1591

1592 - `code: "server_error" or "unsupported_file" or "invalid_file"`

1593

1594 One of `server_error`, `unsupported_file`, or `invalid_file`.

1595

1596 - `"server_error"`

1597

1598 - `"unsupported_file"`

1599

1600 - `"invalid_file"`

1601

1602 - `message: string`

1603

1604 A human-readable description of the error.

1605

1606 - `object: "vector_store.file"`

1607

1608 The object type, which is always `vector_store.file`.

1609

1610 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

1611

1612 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.

1613

1614 - `"in_progress"`

1615

1616 - `"completed"`

1617

1618 - `"cancelled"`

1619

1620 - `"failed"`

1621

1622 - `usage_bytes: number`

1623

1624 The total vector store usage in bytes. Note that this may be different from the original file size.

1625

1626 - `vector_store_id: string`

1627

1628 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

1629

1630 - `attributes: optional map[string or number or boolean]`

1631

1632 Set of 16 key-value pairs that can be attached to an object. This can be

1633 useful for storing additional information about the object in a structured

1634 format, and querying for objects via API or the dashboard. Keys are strings

1635 with a maximum length of 64 characters. Values are strings with a maximum

1636 length of 512 characters, booleans, or numbers.

1637

1638 - `union_member_0: string`

1639

1640 - `union_member_1: number`

1641

1642 - `union_member_2: boolean`

1643

1644 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1645

1646 The strategy used to chunk the file.

1647

1648 - `static_file_chunking_strategy_object: object { static, type }`

1649

1650 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

1651

1652 - `chunk_overlap_tokens: number`

1653

1654 The number of tokens that overlap between chunks. The default value is `400`.

1655

1656 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1657

1658 - `max_chunk_size_tokens: number`

1659

1660 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1661

1662 - `type: "static"`

1663

1664 Always `static`.

1665

1666 - `other_file_chunking_strategy_object: object { type }`

1667

1668 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

1669

1670 - `type: "other"`

1671

1672 Always `other`.

1673

1674### Example

1675

1676```cli

1677openai vector-stores:files retrieve \

1678 --api-key 'My API Key' \

1679 --vector-store-id vs_abc123 \

1680 --file-id file-abc123

1681```

1682

1683#### Response

1684

1685```json

1686{

1687 "id": "id",

1688 "created_at": 0,

1689 "last_error": {

1690 "code": "server_error",

1691 "message": "message"

1692 },

1693 "object": "vector_store.file",

1694 "status": "in_progress",

1695 "usage_bytes": 0,

1696 "vector_store_id": "vector_store_id",

1697 "attributes": {

1698 "foo": "string"

1699 },

1700 "chunking_strategy": {

1701 "static": {

1702 "chunk_overlap_tokens": 0,

1703 "max_chunk_size_tokens": 100

1704 },

1705 "type": "static"

1706 }

1707}

1708```

1709

1710## Delete vector store file

1711

1712`$ openai vector-stores:files delete`

1713

1714**delete** `/vector_stores/{vector_store_id}/files/{file_id}`

1715

1716Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the [delete file](https://platform.openai.com/docs/api-reference/files/delete) endpoint.

1717

1718### Parameters

1719

1720- `--vector-store-id: string`

1721

1722 The ID of the vector store that the file belongs to.

1723

1724- `--file-id: string`

1725

1726 The ID of the file to delete.

1727

1728### Returns

1729

1730- `vector_store_file_deleted: object { id, deleted, object }`

1731

1732 - `id: string`

1733

1734 - `deleted: boolean`

1735

1736 - `object: "vector_store.file.deleted"`

1737

1738### Example

1739

1740```cli

1741openai vector-stores:files delete \

1742 --api-key 'My API Key' \

1743 --vector-store-id vector_store_id \

1744 --file-id file_id

1745```

1746

1747#### Response

1748

1749```json

1750{

1751 "id": "id",

1752 "deleted": true,

1753 "object": "vector_store.file.deleted"

1754}

1755```

1756

1757## Retrieve vector store file content

1758

1759`$ openai vector-stores:files content`

1760

1761**get** `/vector_stores/{vector_store_id}/files/{file_id}/content`

1762

1763Retrieve the parsed contents of a vector store file.

1764

1765### Parameters

1766

1767- `--vector-store-id: string`

1768

1769 The ID of the vector store.

1770

1771- `--file-id: string`

1772

1773 The ID of the file within the vector store.

1774

1775### Returns

1776

1777- `VectorStoreFileContentResponse: object { data, has_more, next_page, object }`

1778

1779 Represents the parsed content of a vector store file.

1780

1781 - `data: array of object { text, type }`

1782

1783 Parsed content of the file.

1784

1785 - `text: optional string`

1786

1787 The text content

1788

1789 - `type: optional string`

1790

1791 The content type (currently only `"text"`)

1792

1793 - `has_more: boolean`

1794

1795 Indicates if there are more content pages to fetch.

1796

1797 - `next_page: string`

1798

1799 The token for the next page, if any.

1800

1801 - `object: "vector_store.file_content.page"`

1802

1803 The object type, which is always `vector_store.file_content.page`

1804

1805### Example

1806

1807```cli

1808openai vector-stores:files content \

1809 --api-key 'My API Key' \

1810 --vector-store-id vs_abc123 \

1811 --file-id file-abc123

1812```

1813

1814#### Response

1815

1816```json

1817{

1818 "data": [

1819 {

1820 "text": "text",

1821 "type": "type"

1822 }

1823 ],

1824 "has_more": true,

1825 "next_page": "next_page",

1826 "object": "vector_store.file_content.page"

1827}

1828```

1829

1830## Domain Types

1831

1832### Vector Store File

1833

1834- `vector_store_file: object { id, created_at, last_error, 6 more }`

1835

1836 A list of files attached to a vector store.

1837

1838 - `id: string`

1839

1840 The identifier, which can be referenced in API endpoints.

1841

1842 - `created_at: number`

1843

1844 The Unix timestamp (in seconds) for when the vector store file was created.

1845

1846 - `last_error: object { code, message }`

1847

1848 The last error associated with this vector store file. Will be `null` if there are no errors.

1849

1850 - `code: "server_error" or "unsupported_file" or "invalid_file"`

1851

1852 One of `server_error`, `unsupported_file`, or `invalid_file`.

1853

1854 - `"server_error"`

1855

1856 - `"unsupported_file"`

1857

1858 - `"invalid_file"`

1859

1860 - `message: string`

1861

1862 A human-readable description of the error.

1863

1864 - `object: "vector_store.file"`

1865

1866 The object type, which is always `vector_store.file`.

1867

1868 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

1869

1870 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.

1871

1872 - `"in_progress"`

1873

1874 - `"completed"`

1875

1876 - `"cancelled"`

1877

1878 - `"failed"`

1879

1880 - `usage_bytes: number`

1881

1882 The total vector store usage in bytes. Note that this may be different from the original file size.

1883

1884 - `vector_store_id: string`

1885

1886 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

1887

1888 - `attributes: optional map[string or number or boolean]`

1889

1890 Set of 16 key-value pairs that can be attached to an object. This can be

1891 useful for storing additional information about the object in a structured

1892 format, and querying for objects via API or the dashboard. Keys are strings

1893 with a maximum length of 64 characters. Values are strings with a maximum

1894 length of 512 characters, booleans, or numbers.

1895

1896 - `union_member_0: string`

1897

1898 - `union_member_1: number`

1899

1900 - `union_member_2: boolean`

1901

1902 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1903

1904 The strategy used to chunk the file.

1905

1906 - `static_file_chunking_strategy_object: object { static, type }`

1907

1908 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

1909

1910 - `chunk_overlap_tokens: number`

1911

1912 The number of tokens that overlap between chunks. The default value is `400`.

1913

1914 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1915

1916 - `max_chunk_size_tokens: number`

1917

1918 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1919

1920 - `type: "static"`

1921

1922 Always `static`.

1923

1924 - `other_file_chunking_strategy_object: object { type }`

1925

1926 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

1927

1928 - `type: "other"`

1929

1930 Always `other`.

1931

1932### Vector Store File Deleted

1933

1934- `vector_store_file_deleted: object { id, deleted, object }`

1935

1936 - `id: string`

1937

1938 - `deleted: boolean`

1939

1940 - `object: "vector_store.file.deleted"`

1941

1942# File Batches

1943

1944## Create vector store file batch

1945

1946`$ openai vector-stores:file-batches create`

1947

1948**post** `/vector_stores/{vector_store_id}/file_batches`

1949

1950Create a vector store file batch.

1951

1952### Parameters

1953

1954- `--vector-store-id: string`

1955

1956 The ID of the vector store for which to create a File Batch.

1957

1958- `--attributes: optional map[string or number or boolean]`

1959

1960 Set of 16 key-value pairs that can be attached to an object. This can be

1961 useful for storing additional information about the object in a structured

1962 format, and querying for objects via API or the dashboard. Keys are strings

1963 with a maximum length of 64 characters. Values are strings with a maximum

1964 length of 512 characters, booleans, or numbers.

1965

1966- `--chunking-strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

1967

1968 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. Only applicable if `file_ids` is non-empty.

1969

1970- `--file-id: optional array of string`

1971

1972 A list of [File](https://platform.openai.com/docs/api-reference/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`.

1973

1974- `--file: optional array of object { file_id, attributes, chunking_strategy }`

1975

1976 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`.

1977

1978### Returns

1979

1980- `vector_store_file_batch: object { id, created_at, file_counts, 3 more }`

1981

1982 A batch of files attached to a vector store.

1983

1984 - `id: string`

1985

1986 The identifier, which can be referenced in API endpoints.

1987

1988 - `created_at: number`

1989

1990 The Unix timestamp (in seconds) for when the vector store files batch was created.

1991

1992 - `file_counts: object { cancelled, completed, failed, 2 more }`

1993

1994 - `cancelled: number`

1995

1996 The number of files that where cancelled.

1997

1998 - `completed: number`

1999

2000 The number of files that have been processed.

2001

2002 - `failed: number`

2003

2004 The number of files that have failed to process.

2005

2006 - `in_progress: number`

2007

2008 The number of files that are currently being processed.

2009

2010 - `total: number`

2011

2012 The total number of files.

2013

2014 - `object: "vector_store.files_batch"`

2015

2016 The object type, which is always `vector_store.file_batch`.

2017

2018 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

2019

2020 The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`.

2021

2022 - `"in_progress"`

2023

2024 - `"completed"`

2025

2026 - `"cancelled"`

2027

2028 - `"failed"`

2029

2030 - `vector_store_id: string`

2031

2032 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

2033

2034### Example

2035

2036```cli

2037openai vector-stores:file-batches create \

2038 --api-key 'My API Key' \

2039 --vector-store-id vs_abc123

2040```

2041

2042#### Response

2043

2044```json

2045{

2046 "id": "id",

2047 "created_at": 0,

2048 "file_counts": {

2049 "cancelled": 0,

2050 "completed": 0,

2051 "failed": 0,

2052 "in_progress": 0,

2053 "total": 0

2054 },

2055 "object": "vector_store.files_batch",

2056 "status": "in_progress",

2057 "vector_store_id": "vector_store_id"

2058}

2059```

2060

2061## Retrieve vector store file batch

2062

2063`$ openai vector-stores:file-batches retrieve`

2064

2065**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}`

2066

2067Retrieves a vector store file batch.

2068

2069### Parameters

2070

2071- `--vector-store-id: string`

2072

2073 The ID of the vector store that the file batch belongs to.

2074

2075- `--batch-id: string`

2076

2077 The ID of the file batch being retrieved.

2078

2079### Returns

2080

2081- `vector_store_file_batch: object { id, created_at, file_counts, 3 more }`

2082

2083 A batch of files attached to a vector store.

2084

2085 - `id: string`

2086

2087 The identifier, which can be referenced in API endpoints.

2088

2089 - `created_at: number`

2090

2091 The Unix timestamp (in seconds) for when the vector store files batch was created.

2092

2093 - `file_counts: object { cancelled, completed, failed, 2 more }`

2094

2095 - `cancelled: number`

2096

2097 The number of files that where cancelled.

2098

2099 - `completed: number`

2100

2101 The number of files that have been processed.

2102

2103 - `failed: number`

2104

2105 The number of files that have failed to process.

2106

2107 - `in_progress: number`

2108

2109 The number of files that are currently being processed.

2110

2111 - `total: number`

2112

2113 The total number of files.

2114

2115 - `object: "vector_store.files_batch"`

2116

2117 The object type, which is always `vector_store.file_batch`.

2118

2119 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

2120

2121 The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`.

2122

2123 - `"in_progress"`

2124

2125 - `"completed"`

2126

2127 - `"cancelled"`

2128

2129 - `"failed"`

2130

2131 - `vector_store_id: string`

2132

2133 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

2134

2135### Example

2136

2137```cli

2138openai vector-stores:file-batches retrieve \

2139 --api-key 'My API Key' \

2140 --vector-store-id vs_abc123 \

2141 --batch-id vsfb_abc123

2142```

2143

2144#### Response

2145

2146```json

2147{

2148 "id": "id",

2149 "created_at": 0,

2150 "file_counts": {

2151 "cancelled": 0,

2152 "completed": 0,

2153 "failed": 0,

2154 "in_progress": 0,

2155 "total": 0

2156 },

2157 "object": "vector_store.files_batch",

2158 "status": "in_progress",

2159 "vector_store_id": "vector_store_id"

2160}

2161```

2162

2163## Cancel vector store file batch

2164

2165`$ openai vector-stores:file-batches cancel`

2166

2167**post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`

2168

2169Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.

2170

2171### Parameters

2172

2173- `--vector-store-id: string`

2174

2175 The ID of the vector store that the file batch belongs to.

2176

2177- `--batch-id: string`

2178

2179 The ID of the file batch to cancel.

2180

2181### Returns

2182

2183- `vector_store_file_batch: object { id, created_at, file_counts, 3 more }`

2184

2185 A batch of files attached to a vector store.

2186

2187 - `id: string`

2188

2189 The identifier, which can be referenced in API endpoints.

2190

2191 - `created_at: number`

2192

2193 The Unix timestamp (in seconds) for when the vector store files batch was created.

2194

2195 - `file_counts: object { cancelled, completed, failed, 2 more }`

2196

2197 - `cancelled: number`

2198

2199 The number of files that where cancelled.

2200

2201 - `completed: number`

2202

2203 The number of files that have been processed.

2204

2205 - `failed: number`

2206

2207 The number of files that have failed to process.

2208

2209 - `in_progress: number`

2210

2211 The number of files that are currently being processed.

2212

2213 - `total: number`

2214

2215 The total number of files.

2216

2217 - `object: "vector_store.files_batch"`

2218

2219 The object type, which is always `vector_store.file_batch`.

2220

2221 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

2222

2223 The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`.

2224

2225 - `"in_progress"`

2226

2227 - `"completed"`

2228

2229 - `"cancelled"`

2230

2231 - `"failed"`

2232

2233 - `vector_store_id: string`

2234

2235 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

2236

2237### Example

2238

2239```cli

2240openai vector-stores:file-batches cancel \

2241 --api-key 'My API Key' \

2242 --vector-store-id vector_store_id \

2243 --batch-id batch_id

2244```

2245

2246#### Response

2247

2248```json

2249{

2250 "id": "id",

2251 "created_at": 0,

2252 "file_counts": {

2253 "cancelled": 0,

2254 "completed": 0,

2255 "failed": 0,

2256 "in_progress": 0,

2257 "total": 0

2258 },

2259 "object": "vector_store.files_batch",

2260 "status": "in_progress",

2261 "vector_store_id": "vector_store_id"

2262}

2263```

2264

2265## List vector store files in a batch

2266

2267`$ openai vector-stores:file-batches list-files`

2268

2269**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`

2270

2271Returns a list of vector store files in a batch.

2272

2273### Parameters

2274

2275- `--vector-store-id: string`

2276

2277 The ID of the vector store that the files belong to.

2278

2279- `--batch-id: string`

2280

2281 The ID of the file batch that the files belong to.

2282

2283- `--after: optional string`

2284

2285 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

2286

2287- `--before: optional string`

2288

2289 A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

2290

2291- `--filter: optional "in_progress" or "completed" or "failed" or "cancelled"`

2292

2293 Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.

2294

2295- `--limit: optional number`

2296

2297 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

2298

2299- `--order: optional "asc" or "desc"`

2300

2301 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

2302

2303### Returns

2304

2305- `ListVectorStoreFilesResponse: object { data, first_id, has_more, 2 more }`

2306

2307 - `data: array of VectorStoreFile`

2308

2309 - `id: string`

2310

2311 The identifier, which can be referenced in API endpoints.

2312

2313 - `created_at: number`

2314

2315 The Unix timestamp (in seconds) for when the vector store file was created.

2316

2317 - `last_error: object { code, message }`

2318

2319 The last error associated with this vector store file. Will be `null` if there are no errors.

2320

2321 - `code: "server_error" or "unsupported_file" or "invalid_file"`

2322

2323 One of `server_error`, `unsupported_file`, or `invalid_file`.

2324

2325 - `"server_error"`

2326

2327 - `"unsupported_file"`

2328

2329 - `"invalid_file"`

2330

2331 - `message: string`

2332

2333 A human-readable description of the error.

2334

2335 - `object: "vector_store.file"`

2336

2337 The object type, which is always `vector_store.file`.

2338

2339 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

2340

2341 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.

2342

2343 - `"in_progress"`

2344

2345 - `"completed"`

2346

2347 - `"cancelled"`

2348

2349 - `"failed"`

2350

2351 - `usage_bytes: number`

2352

2353 The total vector store usage in bytes. Note that this may be different from the original file size.

2354

2355 - `vector_store_id: string`

2356

2357 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

2358

2359 - `attributes: optional map[string or number or boolean]`

2360

2361 Set of 16 key-value pairs that can be attached to an object. This can be

2362 useful for storing additional information about the object in a structured

2363 format, and querying for objects via API or the dashboard. Keys are strings

2364 with a maximum length of 64 characters. Values are strings with a maximum

2365 length of 512 characters, booleans, or numbers.

2366

2367 - `union_member_0: string`

2368

2369 - `union_member_1: number`

2370

2371 - `union_member_2: boolean`

2372

2373 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

2374

2375 The strategy used to chunk the file.

2376

2377 - `static_file_chunking_strategy_object: object { static, type }`

2378

2379 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`

2380

2381 - `chunk_overlap_tokens: number`

2382

2383 The number of tokens that overlap between chunks. The default value is `400`.

2384

2385 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

2386

2387 - `max_chunk_size_tokens: number`

2388

2389 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

2390

2391 - `type: "static"`

2392

2393 Always `static`.

2394

2395 - `other_file_chunking_strategy_object: object { type }`

2396

2397 This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API.

2398

2399 - `type: "other"`

2400

2401 Always `other`.

2402

2403 - `first_id: string`

2404

2405 - `has_more: boolean`

2406

2407 - `last_id: string`

2408

2409 - `object: string`

2410

2411### Example

2412

2413```cli

2414openai vector-stores:file-batches list-files \

2415 --api-key 'My API Key' \

2416 --vector-store-id vector_store_id \

2417 --batch-id batch_id

2418```

2419

2420#### Response

2421

2422```json

2423{

2424 "data": [

2425 {

2426 "id": "id",

2427 "created_at": 0,

2428 "last_error": {

2429 "code": "server_error",

2430 "message": "message"

2431 },

2432 "object": "vector_store.file",

2433 "status": "in_progress",

2434 "usage_bytes": 0,

2435 "vector_store_id": "vector_store_id",

2436 "attributes": {

2437 "foo": "string"

2438 },

2439 "chunking_strategy": {

2440 "static": {

2441 "chunk_overlap_tokens": 0,

2442 "max_chunk_size_tokens": 100

2443 },

2444 "type": "static"

2445 }

2446 }

2447 ],

2448 "first_id": "file-abc123",

2449 "has_more": false,

2450 "last_id": "file-abc456",

2451 "object": "list"

2452}

2453```

2454

2455## Domain Types

2456

2457### Vector Store File Batch

2458

2459- `vector_store_file_batch: object { id, created_at, file_counts, 3 more }`

2460

2461 A batch of files attached to a vector store.

2462

2463 - `id: string`

2464

2465 The identifier, which can be referenced in API endpoints.

2466

2467 - `created_at: number`

2468

2469 The Unix timestamp (in seconds) for when the vector store files batch was created.

2470

2471 - `file_counts: object { cancelled, completed, failed, 2 more }`

2472

2473 - `cancelled: number`

2474

2475 The number of files that where cancelled.

2476

2477 - `completed: number`

2478

2479 The number of files that have been processed.

2480

2481 - `failed: number`

2482

2483 The number of files that have failed to process.

2484

2485 - `in_progress: number`

2486

2487 The number of files that are currently being processed.

2488

2489 - `total: number`

2490

2491 The total number of files.

2492

2493 - `object: "vector_store.files_batch"`

2494

2495 The object type, which is always `vector_store.file_batch`.

2496

2497 - `status: "in_progress" or "completed" or "cancelled" or "failed"`

2498

2499 The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`.

2500

2501 - `"in_progress"`

2502

2503 - `"completed"`

2504

2505 - `"cancelled"`

2506

2507 - `"failed"`

2508

2509 - `vector_store_id: string`

2510

2511 The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to.

cli/resources/vector_stores/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

Vector Stores

List vector stores

Parameters

Returns

Example

Response

Create vector store

Parameters

Returns

Example

Response

Retrieve vector store

Parameters

Returns

Example

Response

Modify vector store

Parameters

Returns

Example

Response

Delete vector store

Parameters

Returns

Example

Response

Search vector store

Parameters

Returns

Example

Response

Domain Types

Auto File Chunking Strategy Param

File Chunking Strategy

File Chunking Strategy Param

Other File Chunking Strategy Object

Static File Chunking Strategy

Static File Chunking Strategy Object

Static File Chunking Strategy Object Param

Vector Store

Vector Store Deleted

Files

List vector store files

Parameters

Returns

Example

Response

Create vector store file

Parameters

Returns

Example

Response

Update vector store file attributes

Parameters

Returns

Example

Response

Retrieve vector store file

Parameters

Returns

Example

Response

Delete vector store file

Parameters

Returns

Example

Response

Retrieve vector store file content

Parameters

Returns

Example

Response

Domain Types

Vector Store File

Vector Store File Deleted

File Batches

Create vector store file batch

Parameters

Returns