Vector Stores

List vector stores

get /vector_stores

List 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 vector store

Body Parameters

chunking_strategy: optional FileChunkingStrategyParam

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}

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

Modify 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 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 vector store

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

FileChunkingStrategy = 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"

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

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

List 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 FileChunkingStrategy
  
  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 vector store file

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

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 FileChunkingStrategy
  
  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 vector store file attributes

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

Retrieve 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 FileChunkingStrategy
  
  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 vector store file

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 vector store file content

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 FileChunkingStrategy
  
  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 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. 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"
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. Only applicable if file_ids is non-empty.

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}

Retrieve 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 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/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

List 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 FileChunkingStrategy
  
  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 +77 −41

4 4

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

6 6

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

8 8

9### Query Parameters9### Query Parameters

10 10

226 226

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

228 228

229Create a vector store.229Create vector store

230 230

231### Body Parameters231### Body Parameters

232 232

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

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](/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](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.

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

470Retrieves a vector store.470Retrieve 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

627Modifies a vector store.627Modify 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 a vector store.828Delete 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 a vector store for relevant chunks based on a query and file attributes filter.889Search vector store

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

1178### File Chunking Strategy Param1214### File Chunking Strategy Param

1179 1215

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

1181 1217

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

1183 1219

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

1185 1221

1438 1474

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

1440 1476

1441Returns a list of vector store files.1477List vector store files

1442 1478

1443### Path Parameters1479### Path Parameters

1444 1480

1532 1568

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

1534 1570

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

1536 1572

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

1538 1574

1548 1584

1549 - `boolean`1585 - `boolean`

1550 1586

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

1552 1588

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

1554 1590

1671 1707

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

1673 1709

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

1675 1711

1676### Path Parameters1712### Path Parameters

1677 1713

1681 1717

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

1683 1719

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

1685 1721

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

1687 1723

1699 1735

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

1701 1737

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

1703 1739

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

1705 1741

1789 1825

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

1791 1827

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

1793 1829

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

1795 1831

1805 1841

1806 - `boolean`1842 - `boolean`

1807 1843

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

1809 1845

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

1811 1847

1908 1944

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

1910 1946

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

1912 1948

1913### Path Parameters1949### Path Parameters

1914 1950

1988 2024

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

1990 2026

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

1992 2028

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

1994 2030

2004 2040

2005 - `boolean`2041 - `boolean`

2006 2042

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

2008 2044

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

2010 2046

2108 2144

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

2110 2146

2111Retrieves a vector store file.2147Retrieve vector store file

2112 2148

2113### Path Parameters2149### Path Parameters

2114 2150

2172 2208

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

2174 2210

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

2176 2212

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

2178 2214

2188 2224

2189 - `boolean`2225 - `boolean`

2190 2226

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

2192 2228

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

2194 2230

2283 2319

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

2285 2321

2286Delete 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.2322Delete vector store file

2287 2323

2288### Path Parameters2324### Path Parameters

2289 2325

2346 2382

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

2348 2384

2349Retrieve the parsed contents of a vector store file.2385Retrieve vector store file content

2350 2386

2351### Path Parameters2387### Path Parameters

2352 2388

2486 2522

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

2488 2524

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

2490 2526

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

2492 2528

2502 2538

2503 - `boolean`2539 - `boolean`

2504 2540

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

2506 2542

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

2508 2544

2566 2602

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

2568 2604

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

2570 2606

2571### Path Parameters2607### Path Parameters

2572 2608

2590 2626

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

2592 2628

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

2594 2630

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

2596 2632

2626 2662

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

2628 2664

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

2630 2666

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

2632 2668

2634 2670

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

2636 2672

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

2638 2674

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

2640 2676

2652 2688

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

2654 2690

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

2656 2692

2657### Returns2693### Returns

2658 2694

2710 2746

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

2712 2748

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

2714 2750

2715### Example2751### Example

2716 2752

2789 2825

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

2791 2827

2792Retrieves a vector store file batch.2828Retrieve vector store file batch

2793 2829

2794### Path Parameters2830### Path Parameters

2795 2831

2853 2889

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

2855 2891

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

2857 2893

2858### Example2894### Example

2859 2895

2914 2950

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

2916 2952

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

2918 2954

2919### Path Parameters2955### Path Parameters

2920 2956

2978 3014

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

2980 3016

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

2982 3018

2983### Example3019### Example

2984 3020

3041 3077

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

3043 3079

3044Returns a list of vector store files in a batch.3080List vector store files in a batch

3045 3081

3046### Path Parameters3082### Path Parameters

3047 3083

3137 3173

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

3139 3175

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

3141 3177

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

3143 3179

3153 3189

3154 - `boolean`3190 - `boolean`

3155 3191

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

3157 3193

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

3159 3195

3330 3366

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

3332 3368

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

resources/vector_stores/index.md 2026-07-07 08:02 UTC to 2026-07-09 20: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

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