Search in vector store's file

Perform semantic search within a vector store and filter down to a specific file. Provide the file_id to search within the file, don’t confuse it with parse_result_id, because the two are connected.

This endpoint performs vector-based semantic search to find the most relevant content based on the provided query. The search uses embeddings to find semantically similar content.

Search Parameters:

• query: The search query text
• top_k: Number of results to return (ranked by relevance)
• filters: Optional filters to narrow search scope (e.g., by file_id)

Authentication:

• Credentials can be provided either through project-level credentials or request-level credentials
• For SGP Knowledge Base, SGP credentials are required

Returns:

• Ranked list of relevant content chunks
• Each chunk includes content, source blocks, relevance score, and parse result ID
• Results are ordered by relevance score (highest first)

Example Request:

{
    "query": "What are the main features of the product?",
    "top_k": 5,
    "filters": {
        "file_id": "file_123"
    },
    "credentials": {
        "sgp": {
            "api_key": "your-api-key",
            "base_url": "https://api.example.com"
        }
    }
}

Example Response:

{
    "chunks": [
        {
            "content": "The product includes advanced analytics, real-time monitoring, and automated reporting features.",
            "blocks": [
                {
                    "id": "block_123",
                    "content": "The product includes advanced analytics...",
                    "type": "text"
                }
            ],
            "score": 0.95,
            "parse_result_id": "parse_123"
        }
    ]
}

POST /v1/projects/{project_id}/vector-stores/{vector_store_id}/files/{file_id}/search

Search in vector store's file

cURL

curl --request POST \
  --url https://api.example.com/v1/projects/{project_id}/vector-stores/{vector_store_id}/files/{file_id}/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-selected-account-id: <api-key>' \
  --data '
{
  "query": "<string>",
  "top_k": 123,
  "filters": {},
  "rerank_config": {
    "model": "<string>",
    "top_n": 2,
    "instruction": "<string>"
  },
  "query_type": "semantic"
}
'

200

{
  "chunks": [
    {
      "content": "<string>",
      "blocks": [
        {
          "type": "<string>",
          "content": "<string>",
          "bbox": {
            "left": 123,
            "top": 123,
            "width": 123,
            "height": 123
          },
          "confidence": 123,
          "page_number": 0
        }
      ],
      "score": 123,
      "file_id": "<string>",
      "parse_result_id": "<string>",
      "metadata": {}
    }
  ]
}

Authorizations

x-api-key · string · header · required

API key for authentication

x-selected-account-id · string · header · required

Selected Account ID

Path Parameters

project_id · string · required

vector_store_id · string · required

file_id · string · required

Body

application/json

Search parameters for vector store engines. Extend this model to add new parameters without changing the engine interface.

query · string · required

Query to search for

top_k · integer | null

Number of results to return

filters · Filters · object

Filters to apply to the search. For example, {file_id: 123}

Show child attributes

rerank_config · RerankConfig · object

Reranking configuration. This is only applicable for SGP Vector Stores.

Show child attributes

query_type · enum<string> | null

Type of query to perform.

Available options: semantic, lexical, hybrid

Response

200

application/json

Search completed successfully

chunks · VectorStoreChunk · object[] · required

Chunks of the search result

Show child attributes