> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search in vector store

> Perform semantic search within a vector store.
    
    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:**
    ```json
    {
        "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:**
    ```json
    {
        "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"
            }
        ]
    }
    ```



## OpenAPI

````yaml https://dex.sgp.scale.com/openapi.json post /v1/projects/{project_id}/vector-stores/{vector_store_id}/search
openapi: 3.1.0
info:
  title: Document Understanding API
  description: API for uploading and processing documents
  version: 0.4.5
servers: []
security:
  - ApiKey: []
    AccountId: []
tags:
  - name: Projects
    description: Operations related to project creation and management
  - name: Files
    description: Operations related to file upload and access
  - name: Parse
    description: Operations related to starting parse jobs and accessing their results
  - name: Vector Stores
    description: Operations related to vector store creation and management
  - name: Extract
    description: Operations related to starting extract jobs and accessing their results
  - name: Research
    description: Dex Research agent kickoff and results.
  - name: Jobs
    description: Operations related to monitoring jobs and their status
paths:
  /v1/projects/{project_id}/vector-stores/{vector_store_id}/search:
    post:
      tags:
        - Vector Stores
      summary: Search in vector store
      description: |-
        Perform semantic search within a vector store.
            
            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:**
            ```json
            {
                "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:**
            ```json
            {
                "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"
                    }
                ]
            }
            ```
      operationId: >-
        search_in_vector_store_v1_projects__project_id__vector_stores__vector_store_id__search_post
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            title: Project Id
        - name: vector_store_id
          in: path
          required: true
          schema:
            type: string
            title: Vector Store Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VectorStoreSearchParams'
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VectorStoreSearchResult'
        '400':
          description: Bad request - Invalid credentials or missing required fields
        '404':
          description: Project or vector store not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error - Search operation failed
components:
  schemas:
    VectorStoreSearchParams:
      properties:
        top_k:
          anyOf:
            - type: integer
            - type: 'null'
          title: Top K
          description: Number of results to return
        filters:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - additionalProperties: true
                    type: object
              type: object
            - type: 'null'
          title: Filters
          description: 'Filters to apply to the search. For example, {file_id: 123}'
        rerank_config:
          anyOf:
            - $ref: '#/components/schemas/RerankConfig'
            - type: 'null'
          description: >-
            Reranking configuration. This is only applicable for SGP Vector
            Stores.
        query:
          type: string
          title: Query
          description: Query to search for
        query_type:
          anyOf:
            - type: string
              enum:
                - semantic
                - lexical
                - hybrid
            - type: 'null'
          title: Query Type
          description: Type of query to perform.
      additionalProperties: true
      type: object
      required:
        - query
      title: VectorStoreSearchParams
      description: >-
        Search parameters for vector store engines. Extend this model to add new
        parameters without changing the engine interface.
    VectorStoreSearchResult:
      properties:
        chunks:
          items:
            $ref: '#/components/schemas/VectorStoreChunk'
          type: array
          title: Chunks
          description: Chunks of the search result
      type: object
      required:
        - chunks
      title: VectorStoreSearchResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RerankConfig:
      properties:
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Reranking model to use (uses system default if not specified)
        top_n:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Top N
          description: Number of results to keep after reranking (defaults to top_k)
        instruction:
          anyOf:
            - type: string
            - type: 'null'
          title: Instruction
          description: >-
            Custom instruction for the reranking model (e.g., 'Given a medical
            question, retrieve relevant clinical passages'). Only applies to
            instruction-following rerankers like Qwen3.
      type: object
      title: RerankConfig
    VectorStoreChunk:
      properties:
        content:
          type: string
          title: Content
          description: Content of the chunk
        blocks:
          items:
            $ref: '#/components/schemas/ParseBlock'
          type: array
          title: Blocks
          description: Blocks of the chunk
        score:
          type: number
          title: Score
          description: Score of the chunk
        file_id:
          anyOf:
            - type: string
            - type: 'null'
          title: File Id
          description: ID of the file
        parse_result_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parse Result Id
          description: ID of the parse result
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional metadata from the chunk
      type: object
      required:
        - content
        - blocks
        - score
        - file_id
        - parse_result_id
      title: VectorStoreChunk
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ParseBlock:
      properties:
        type:
          type: string
          title: Type
          description: Block type (text, table, figure, header, etc.)
        content:
          type: string
          title: Content
          description: The actual content (text, HTML, etc.)
        bbox:
          $ref: '#/components/schemas/BoundingBox'
          description: Bounding box locations for this block
        confidence:
          type: number
          title: Confidence
          description: Confidence score (0-1)
        page_number:
          type: integer
          title: Page Number
          description: Page number on the document
          default: 0
      type: object
      required:
        - type
        - content
        - bbox
        - confidence
      title: ParseBlock
      description: A block of content from parsing with location information.
    BoundingBox:
      properties:
        left:
          type: number
          title: Left
          description: Left coordinate
        top:
          type: number
          title: Top
          description: Top coordinate
        width:
          type: number
          title: Width
          description: Width
        height:
          type: number
          title: Height
          description: Height
      type: object
      required:
        - left
        - top
        - width
        - height
      title: BoundingBox
      description: Bounding box information for location in document.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
    AccountId:
      type: apiKey
      in: header
      name: x-selected-account-id
      description: Selected Account ID

````