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

POST /vector_stores/{vector_store_id}/search
Api key auth

Path parameters

  • vector_store_id string Required

    The ID of the vector store to search.

application/json

Body Required

  • query string | array[string] Required

    A query string for a search

    One of:
    string-1 string array-2 array[string]
  • rewrite_query boolean

    Whether to rewrite the natural language query for vector search.

    Default value is false.

  • max_num_results integer

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

    Minimum value is 1, maximum value is 50. Default value is 10.

  • filters object

    A filter to apply based on file attributes.

    One of:
    ComparisonFilter object CompoundFilter object

    A filter used to compare a specified attribute key to a given value using a defined comparison operation.

    Hide attributes Show attributes
    • type string Required

      Specifies the comparison operator: eq, ne, gt, gte, lt, lte.

      • eq: equals
      • ne: not equal
      • gt: greater than
      • gte: greater than or equal
      • lt: less than
      • lte: less than or equal

      Values are eq, ne, gt, gte, lt, or lte. Default value is eq.

    • key string Required

      The key to compare against the value.

    • value string | number | boolean Required

      The value to compare against the attribute key; supports string, number, or boolean types.

      One of:
      string-1 string number-2 number boolean-3 boolean
  • ranking_options object

    Ranking options for search.

    Additional properties are NOT allowed.

    Hide ranking_options attributes Show ranking_options attributes object
    • ranker string

      Values are auto or default-2024-11-15. Default value is auto.

    • score_threshold number

      Minimum value is 0, maximum value is 1. Default value is 0.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • object string Required

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

      Value is vector_store.search_results.page.

    • search_query array[string] Required

      The query used for this search.

    • data array[object] Required

      The list of search result items.

      Hide data attributes Show data attributes object
      • file_id string Required

        The ID of the vector store file.

      • filename string Required

        The name of the vector store file.

      • score number Required

        The similarity score for the result.

        Minimum value is 0, maximum value is 1.

      • attributes object | null Required

        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.

      • content array[object] Required

        Content chunks from the file.

        Hide content attributes Show content attributes object
        • type string Required

          The type of content.

          Value is text.

        • text string Required

          The text content returned from search.

    • has_more boolean Required

      Indicates if there are more results to fetch.

    • next_page string | null Required

      The token for the next page, if any.
POST /vector_stores/{vector_store_id}/search 
curl \
 --request POST 'https://api.openai.com/v1/vector_stores/vs_abc123/search' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"query":"string","rewrite_query":false,"max_num_results":10,"filters":{"type":"eq","key":"string","value":"string"},"ranking_options":{"ranker":"auto","score_threshold":0}}'
Request examples 
{
  "query": "string",
  "rewrite_query": false,
  "max_num_results": 10,
  "filters": {
    "type": "eq",
    "key": "string",
    "value": "string"
  },
  "ranking_options": {
    "ranker": "auto",
    "score_threshold": 0
  }
}
Response examples (200) 
{
  "object": "vector_store.search_results.page",
  "search_query": [
    "string"
  ],
  "data": [
    {
      "file_id": "string",
      "filename": "string",
      "score": 42.0,
      "attributes": {},
      "content": [
        {
          "type": "text",
          "text": "string"
        }
      ]
    }
  ],
  "has_more": true,
  "next_page": "string"
}