Vector Stores

List vector stores

get /vector_stores

Returns a list of vector stores.

Query 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.
- "asc"
- "desc"

Returns

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: Metadata
  
  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.
  - "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.
    - "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

curl https://api.openai.com/v1/vector_stores \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_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"
}

Example

curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "object": "list",
  "data": [
    {
      "id": "vs_abc123",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ",
      "description": "Contains commonly asked questions and answers, organized by topic.",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    },
    {
      "id": "vs_abc456",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ v2",
      "description": null,
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    }
  ],
  "first_id": "vs_abc123",
  "last_id": "vs_abc456",
  "has_more": false
}

Create vector store

post /vector_stores

Create a vector store.

Body 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.
- AutoFileChunkingStrategyParam 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.
    - "auto"
- StaticFileChunkingStrategyObjectParam object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - 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"
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.
- anchor: "last_active_at"
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - "last_active_at"
- days: number
  
  The number of days after the anchor time that the vector store will expire.
file_ids: 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 Metadata

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

VectorStore 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: Metadata
  
  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.
  - "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.
    - "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

curl https://api.openai.com/v1/vector_stores \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

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
}

Example

curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "name": "Support FAQ"
  }'

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "description": "Contains commonly asked questions and answers, organized by topic.",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

Retrieve vector store

get /vector_stores/{vector_store_id}

Retrieves a vector store.

Path Parameters

vector_store_id: string

Returns

VectorStore 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: Metadata
  
  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.
  - "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.
    - "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

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_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
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776
}

Modify vector store

post /vector_stores/{vector_store_id}

Modifies a vector store.

Path Parameters

vector_store_id: string

Body Parameters

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.
  - "last_active_at"
- days: number
  
  The number of days after the anchor time that the vector store will expire.
metadata: optional Metadata

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

VectorStore 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: Metadata
  
  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.
  - "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.
    - "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

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

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
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"
  -d '{
    "name": "Support FAQ"
  }'

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "description": "Contains commonly asked questions and answers, organized by topic.",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

Delete vector store

delete /vector_stores/{vector_store_id}

Delete a vector store.

Path Parameters

vector_store_id: string

Returns

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

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID \
    -X DELETE \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

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

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

Response

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

Search vector store

post /vector_stores/{vector_store_id}/search

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

Path Parameters

vector_store_id: string

Body Parameters

query: string or array of string

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

A filter to apply based on file attributes.
- ComparisonFilter object { key, type, value }
  
  A filter used to compare a specified attribute key to a given value using a defined comparison operation.
  - key: string
    
    The key to compare against the value.
  - type: "eq" or "ne" or "gt" or 5 more
    
    Specifies the comparison operator: eq, ne, gt, gte, lt, lte, in, nin.
    - eq: equals
    - ne: not equal
    - gt: greater than
    - gte: greater than or equal
    - lt: less than
    - lte: less than or equal
    - in: in
    - nin: not in
    - "eq"
    - "ne"
    - "gt"
    - "gte"
    - "lt"
    - "lte"
    - "in"
    - "nin"
  - value: string or number or boolean or array of string or number
    
    The value to compare against the attribute key; supports string, number, or boolean types.
    - string
    - number
    - boolean
    - array of string or number
      - string
      - number
- CompoundFilter object { filters, type }
  
  Combine multiple filters using and or or.
  - filters: array of ComparisonFilter or unknown
    
    Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
    - ComparisonFilter object { key, type, value }
      
      A filter used to compare a specified attribute key to a given value using a defined comparison operation.
    - unknown
  - type: "and" or "or"
    
    Type of operation: and or or.
    - "and"
    - "or"
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.
- ranker: optional "none" or "auto" or "default-2024-11-15"
  
  Enable re-ranking; set to none to disable, which can help reduce latency.
  - "none"
  - "auto"
  - "default-2024-11-15"
- score_threshold: optional number
rewrite_query: optional boolean

Whether to rewrite the natural language query for vector search.

Returns

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.
  - string
  - number
  - 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
- "vector_store.search_results.page"
search_query: array of string

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/search \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "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"
  ]
}

Example

curl -X POST \
https://api.openai.com/v1/vector_stores/vs_abc123/search \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "What is the return policy?", "filters": {...}}'

Response

{
  "object": "vector_store.search_results.page",
  "search_query": "What is the return policy?",
  "data": [
    {
      "file_id": "file_123",
      "filename": "document.pdf",
      "score": 0.95,
      "attributes": {
        "author": "John Doe",
        "date": "2023-01-01"
      },
      "content": [
        {
          "type": "text",
          "text": "Relevant chunk"
        }
      ]
    },
    {
      "file_id": "file_456",
      "filename": "notes.txt",
      "score": 0.89,
      "attributes": {
        "author": "Jane Smith",
        "date": "2023-01-02"
      },
      "content": [
        {
          "type": "text",
          "text": "Sample text content from the vector store."
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

Domain Types

Auto File Chunking Strategy Param

AutoFileChunkingStrategyParam 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.
  - "auto"

File Chunking Strategy Param

FileChunkingStrategyParam = AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.
- AutoFileChunkingStrategyParam 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.
    - "auto"
- StaticFileChunkingStrategyObjectParam object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - 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"

Other File Chunking Strategy Object

OtherFileChunkingStrategyObject 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.
  - "other"

Static File Chunking Strategy

StaticFileChunkingStrategy 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

StaticFileChunkingStrategyObject object { static, type }
- static: StaticFileChunkingStrategy
  - 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"

Static File Chunking Strategy Object Param

StaticFileChunkingStrategyObjectParam object { static, type }

Customize your own chunking strategy by setting chunk size and chunk overlap.
- static: StaticFileChunkingStrategy
  - 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"

Vector Store

VectorStore 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: Metadata
  
  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.
  - "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.
    - "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

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

Vector Store Search Response

VectorStoreSearchResponse object { attributes, content, file_id, 2 more }
- 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.
  - string
  - number
  - 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.

Files

List vector store files

get /vector_stores/{vector_store_id}/files

Returns a list of vector store files.

Path Parameters

vector_store_id: string

Query 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.
filter: optional "in_progress" or "completed" or "failed" or "cancelled"

Filter by file status. One of in_progress, completed, failed, cancelled.
- "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.
- "asc"
- "desc"

Returns

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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"
first_id: string
has_more: boolean
last_id: string
object: string

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    },
    {
      "id": "file-abc456",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

Create vector store file

post /vector_stores/{vector_store_id}/files

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

Path Parameters

vector_store_id: string

Body Parameters

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.
- string
- number
- boolean
chunking_strategy: optional FileChunkingStrategyParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.
- AutoFileChunkingStrategyParam 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.
    - "auto"
- StaticFileChunkingStrategyObjectParam object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - 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"

Returns

VectorStoreFile 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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "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"
  }
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -H "OpenAI-Beta: assistants=v2" \
    -d '{
      "file_id": "file-abc123"
    }'

Response

{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "usage_bytes": 1234,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

Update vector store file attributes

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

Update attributes on a vector store file.

Path Parameters

vector_store_id: string
file_id: string

Body Parameters

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.
- string
- number
- boolean

Returns

VectorStoreFile 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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "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"
  }
}

Example

curl https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attributes": {"key1": "value1", "key2": 2}}'

Response

{
  "id": "file-abc123",
  "object": "vector_store.file",
  "usage_bytes": 1234,
  "created_at": 1699061776,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null,
  "chunking_strategy": {...},
  "attributes": {"key1": "value1", "key2": 2}
}

Retrieve vector store file

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

Retrieves a vector store file.

Path Parameters

vector_store_id: string
file_id: string

Returns

VectorStoreFile 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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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"
  }
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

Delete vector store file

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.

Path Parameters

vector_store_id: string
file_id: string

Returns

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

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID \
    -X DELETE \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

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

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

Response

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

Retrieve vector store file content

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

Retrieve the parsed contents of a vector store file.

Path Parameters

vector_store_id: string
file_id: string

Returns

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
- "vector_store.file_content.page"

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/files/$FILE_ID/content \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

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

Example

curl \
https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \
-H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "file_id": "file-abc123",
  "filename": "example.txt",
  "attributes": {"key": "value"},
  "content": [
    {"type": "text", "text": "..."},
    ...
  ]
}

Domain Types

Vector Store File

VectorStoreFile 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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"

Vector Store File Deleted

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

File Content Response

FileContentResponse object { text, type }
- text: optional string
  
  The text content
- type: optional string
  
  The content type (currently only "text")

File Batches

Create vector store file batch

post /vector_stores/{vector_store_id}/file_batches

Create a vector store file batch.

Path Parameters

vector_store_id: string

Body Parameters

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.
- string
- number
- boolean
chunking_strategy: optional FileChunkingStrategyParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.
- AutoFileChunkingStrategyParam 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.
    - "auto"
- StaticFileChunkingStrategyObjectParam object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - 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_ids: 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.
files: 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.
- 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.
  - string
  - number
  - boolean
- chunking_strategy: optional FileChunkingStrategyParam
  
  The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.

Returns

VectorStoreFileBatch 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.
  - "vector_store.files_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

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

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"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json \
    -H "OpenAI-Beta: assistants=v2" \
    -d '{
      "files": [
        {
          "file_id": "file-abc123",
          "attributes": {"category": "finance"}
        },
        {
          "file_id": "file-abc456",
          "chunking_strategy": {
            "type": "static",
            "max_chunk_size_tokens": 1200,
            "chunk_overlap_tokens": 200
          }
        }
      ]
    }'

Response

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}

Retrieve vector store file batch

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

Retrieves a vector store file batch.

Path Parameters

vector_store_id: string
batch_id: string

Returns

VectorStoreFileBatch 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.
  - "vector_store.files_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

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}

Cancel vector store file batch

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.

Path Parameters

vector_store_id: string
batch_id: string

Returns

VectorStoreFileBatch 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.
  - "vector_store.files_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

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID/cancel \
    -X POST \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X POST

Response

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 12,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 15,
  }
}

List vector store files in a batch

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

Returns a list of vector store files in a batch.

Path Parameters

vector_store_id: string
batch_id: string

Query 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.
filter: optional "in_progress" or "completed" or "failed" or "cancelled"

Filter by file status. One of in_progress, completed, failed, cancelled.
- "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.
- "asc"
- "desc"

Returns

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.
  - "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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - 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"
  - OtherFileChunkingStrategyObject 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.
      - "other"
first_id: string
has_more: boolean
last_id: string
object: string

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID/files \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    },
    {
      "id": "file-abc456",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

Domain Types

Vector Store File Batch

VectorStoreFileBatch 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.
  - "vector_store.files_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.

resources/vector_stores/index.md +41 −77

4 4

5**get** `/vector_stores`5**get** `/vector_stores`

6 6

~~7List vector stores~~7Returns a list of vector stores.

8 8

9### Query Parameters9### Query Parameters

10 10

226 226

227**post** `/vector_stores`227**post** `/vector_stores`

228 228

229Create vector store229Create a vector store.

230 230

231### Body Parameters231### Body Parameters

232 232

233- `chunking_strategy: optional FileChunkingStrategyParam`233- `chunking_strategy: optional AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

234 234

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

236 236

286 286

287- `file_ids: optional array of string`287- `file_ids: optional array of string`

288 288

289 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.289 A list of [File](/docs/api-reference/files) IDs that the vector store should use. Useful for tools like `file_search` that can access files.

290 290

291- `metadata: optional Metadata`291- `metadata: optional Metadata`

292 292

467 467

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

469 469

470Retrieve vector store470Retrieves a vector store.

471 471

472### Path Parameters472### Path Parameters

473 473

624 624

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

626 626

627Modify vector store627Modifies a vector store.

628 628

629### Path Parameters629### Path Parameters

630 630

825 825

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

827 827

828Delete vector store828Delete a vector store.

829 829

830### Path Parameters830### Path Parameters

831 831

886 886

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

888 888

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

890 890

891### Path Parameters891### Path Parameters

892 892

1175 1175

1176 - `"auto"`1176 - `"auto"`

1177 1177

1178### File Chunking Strategy

~~1179~~

1180- `FileChunkingStrategy = StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

~~1181~~

1182 The strategy used to chunk the file.

~~1183~~

1184 - `StaticFileChunkingStrategyObject object { static, type }`

~~1185~~

1186 - `static: StaticFileChunkingStrategy`

~~1187~~

1188 - `chunk_overlap_tokens: number`

~~1189~~

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

~~1191~~

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

~~1193~~

1194 - `max_chunk_size_tokens: number`

~~1195~~

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

~~1197~~

1198 - `type: "static"`

~~1199~~

1200 Always `static`.

~~1201~~

1202 - `"static"`

~~1203~~

1204 - `OtherFileChunkingStrategyObject object { type }`

~~1205~~

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

~~1207~~

1208 - `type: "other"`

~~1209~~

1210 Always `other`.

~~1211~~

1212 - `"other"`

~~1213~~

1214### File Chunking Strategy Param1178### File Chunking Strategy Param

1215 1179

1216- `FileChunkingStrategyParam = AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`1180- `FileChunkingStrategyParam = AutoFileChunkingStrategyParam or StaticFileChunkingStrategyObjectParam`

1217 1181

1218 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.1182 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.

1219 1183

1220 - `AutoFileChunkingStrategyParam object { type }`1184 - `AutoFileChunkingStrategyParam object { type }`

1221 1185

1474 1438

1475**get** `/vector_stores/{vector_store_id}/files`1439**get** `/vector_stores/{vector_store_id}/files`

1476 1440

1477List vector store files1441Returns a list of vector store files.

1478 1442

1479### Path Parameters1443### Path Parameters

1480 1444

1568 1532

1569 - `vector_store_id: string`1533 - `vector_store_id: string`

1570 1534

1571 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.1535 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

1572 1536

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

1574 1538

1584 1548

1585 - `boolean`1549 - `boolean`

1586 1550

1587 - `chunking_strategy: optional FileChunkingStrategy`1551 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1588 1552

1589 The strategy used to chunk the file.1553 The strategy used to chunk the file.

1590 1554

1707 1671

1708**post** `/vector_stores/{vector_store_id}/files`1672**post** `/vector_stores/{vector_store_id}/files`

1709 1673

1710Create vector store file1674Create a vector store file by attaching a [File](/docs/api-reference/files) to a [vector store](/docs/api-reference/vector-stores/object).

1711 1675

1712### Path Parameters1676### Path Parameters

1713 1677

1717 1681

1718- `file_id: string`1682- `file_id: string`

1719 1683

1720 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.1684 A [File](/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`](/docs/api-reference/vector-stores-file-batches/createBatch) to minimize per-vector-store write requests.

1721 1685

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

1723 1687

1735 1699

1736- `chunking_strategy: optional FileChunkingStrategyParam`1700- `chunking_strategy: optional FileChunkingStrategyParam`

1737 1701

1738 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.1702 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.

1739 1703

1740 - `AutoFileChunkingStrategyParam object { type }`1704 - `AutoFileChunkingStrategyParam object { type }`

1741 1705

1825 1789

1826 - `vector_store_id: string`1790 - `vector_store_id: string`

1827 1791

1828 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.1792 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

1829 1793

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

1831 1795

1841 1805

1842 - `boolean`1806 - `boolean`

1843 1807

1844 - `chunking_strategy: optional FileChunkingStrategy`1808 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

1845 1809

1846 The strategy used to chunk the file.1810 The strategy used to chunk the file.

1847 1811

1944 1908

1945**post** `/vector_stores/{vector_store_id}/files/{file_id}`1909**post** `/vector_stores/{vector_store_id}/files/{file_id}`

1946 1910

1947Update vector store file attributes1911Update attributes on a vector store file.

1948 1912

1949### Path Parameters1913### Path Parameters

1950 1914

2024 1988

2025 - `vector_store_id: string`1989 - `vector_store_id: string`

2026 1990

2027 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.1991 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

2028 1992

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

2030 1994

2040 2004

2041 - `boolean`2005 - `boolean`

2042 2006

2043 - `chunking_strategy: optional FileChunkingStrategy`2007 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

2044 2008

2045 The strategy used to chunk the file.2009 The strategy used to chunk the file.

2046 2010

2144 2108

2145**get** `/vector_stores/{vector_store_id}/files/{file_id}`2109**get** `/vector_stores/{vector_store_id}/files/{file_id}`

2146 2110

2147Retrieve vector store file2111Retrieves a vector store file.

2148 2112

2149### Path Parameters2113### Path Parameters

2150 2114

2208 2172

2209 - `vector_store_id: string`2173 - `vector_store_id: string`

2210 2174

2211 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.2175 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

2212 2176

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

2214 2178

2224 2188

2225 - `boolean`2189 - `boolean`

2226 2190

2227 - `chunking_strategy: optional FileChunkingStrategy`2191 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

2228 2192

2229 The strategy used to chunk the file.2193 The strategy used to chunk the file.

2230 2194

2319 2283

2320**delete** `/vector_stores/{vector_store_id}/files/{file_id}`2284**delete** `/vector_stores/{vector_store_id}/files/{file_id}`

2321 2285

2322Delete vector store file2286Delete 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](/docs/api-reference/files/delete) endpoint.

2323 2287

2324### Path Parameters2288### Path Parameters

2325 2289

2382 2346

2383**get** `/vector_stores/{vector_store_id}/files/{file_id}/content`2347**get** `/vector_stores/{vector_store_id}/files/{file_id}/content`

2384 2348

2385Retrieve vector store file content2349Retrieve the parsed contents of a vector store file.

2386 2350

2387### Path Parameters2351### Path Parameters

2388 2352

2522 2486

2523 - `vector_store_id: string`2487 - `vector_store_id: string`

2524 2488

2525 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.2489 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

2526 2490

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

2528 2492

2538 2502

2539 - `boolean`2503 - `boolean`

2540 2504

2541 - `chunking_strategy: optional FileChunkingStrategy`2505 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

2542 2506

2543 The strategy used to chunk the file.2507 The strategy used to chunk the file.

2544 2508

2602 2566

2603**post** `/vector_stores/{vector_store_id}/file_batches`2567**post** `/vector_stores/{vector_store_id}/file_batches`

2604 2568

2605Create vector store file batch2569Create a vector store file batch.

2606 2570

2607### Path Parameters2571### Path Parameters

2608 2572

2626 2590

2627- `chunking_strategy: optional FileChunkingStrategyParam`2591- `chunking_strategy: optional FileChunkingStrategyParam`

2628 2592

2629 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.2593 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.

2630 2594

2631 - `AutoFileChunkingStrategyParam object { type }`2595 - `AutoFileChunkingStrategyParam object { type }`

2632 2596

2662 2626

2663- `file_ids: optional array of string`2627- `file_ids: optional array of string`

2664 2628

2665 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`.2629 A list of [File](/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`.

2666 2630

2667- `files: optional array of object { file_id, attributes, chunking_strategy }`2631- `files: optional array of object { file_id, attributes, chunking_strategy }`

2668 2632

2670 2634

2671 - `file_id: string`2635 - `file_id: string`

2672 2636

2673 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.2637 A [File](/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`](/docs/api-reference/vector-stores-file-batches/createBatch) to minimize per-vector-store write requests.

2674 2638

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

2676 2640

2688 2652

2689 - `chunking_strategy: optional FileChunkingStrategyParam`2653 - `chunking_strategy: optional FileChunkingStrategyParam`

2690 2654

2691 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.2655 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.

2692 2656

2693### Returns2657### Returns

2694 2658

2746 2710

2747 - `vector_store_id: string`2711 - `vector_store_id: string`

2748 2712

2749 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.2713 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

2750 2714

2751### Example2715### Example

2752 2716

2825 2789

2826**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}`2790**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}`

2827 2791

2828Retrieve vector store file batch2792Retrieves a vector store file batch.

2829 2793

2830### Path Parameters2794### Path Parameters

2831 2795

2889 2853

2890 - `vector_store_id: string`2854 - `vector_store_id: string`

2891 2855

2892 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.2856 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

2893 2857

2894### Example2858### Example

2895 2859

2950 2914

2951**post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`2915**post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`

2952 2916

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

2954 2918

2955### Path Parameters2919### Path Parameters

2956 2920

3014 2978

3015 - `vector_store_id: string`2979 - `vector_store_id: string`

3016 2980

3017 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.2981 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

3018 2982

3019### Example2983### Example

3020 2984

3077 3041

3078**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`3042**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`

3079 3043

3080List vector store files in a batch3044Returns a list of vector store files in a batch.

3081 3045

3082### Path Parameters3046### Path Parameters

3083 3047

3173 3137

3174 - `vector_store_id: string`3138 - `vector_store_id: string`

3175 3139

3176 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.3140 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

3177 3141

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

3179 3143

3189 3153

3190 - `boolean`3154 - `boolean`

3191 3155

3192 - `chunking_strategy: optional FileChunkingStrategy`3156 - `chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject`

3193 3157

3194 The strategy used to chunk the file.3158 The strategy used to chunk the file.

3195 3159

3366 3330

3367 - `vector_store_id: string`3331 - `vector_store_id: string`

3368 3332

3369 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.3333 The ID of the [vector store](/docs/api-reference/vector-stores/object) that the [File](/docs/api-reference/files) is attached to.

resources/vector_stores/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

Vector Stores

List vector stores

Query Parameters

Returns

Example

Response

Example

Response

Create vector store

Body Parameters

Returns

Example

Response

Example

Response

Retrieve vector store

Path Parameters

Returns

Example

Response

Example

Response

Modify vector store

Path Parameters

Body Parameters

Returns

Example

Response

Example

Response

Delete vector store

Path Parameters

Returns

Example

Response

Example

Response

Search vector store

Path Parameters

Body Parameters

Returns

Example

Response

Example

Response

Domain Types

Auto File Chunking Strategy Param

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

Vector Store Search Response

Files

List vector store files

Path Parameters

Query Parameters

Returns

Example

Response

Example

Response

Create vector store file

Path Parameters

Body Parameters

Returns

Example

Response

Example

Response

Update vector store file attributes

Path Parameters

Body Parameters

Returns

Example

Response

Example