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

# Top Documents

> Get the top K documents that match the given query



## OpenAPI

````yaml post /queries/top-documents
openapi: 3.1.0
info:
  title: ZeroEntropy API
  description: This API provides access to ZeroEntropy's SoTA retrieval pipeline. Enjoy!
  version: 0.1.0
servers:
  - url: https://api.zeroentropy.dev/v1
    description: ZeroEntropy API
  - url: https://eu-api.zeroentropy.dev/v1
    description: ZeroEntropy API (EU datacenters)
security: []
paths:
  /queries/top-documents:
    post:
      tags:
        - Queries
      summary: Top Documents
      description: Get the top K documents that match the given query
      operationId: top_documents_queries_top_documents_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopDocumentsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopDocumentsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                detail: Description of Error
        '404':
          description: Not Found
          content:
            application/json:
              example:
                detail: Description of Error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    TopDocumentsRequest:
      properties:
        collection_name:
          type: string
          title: Collection Name
          description: The name of the collection.
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: >-
            The natural language query to search with. This cannot exceed 4096
            UTF-8 bytes. If `null`, then the sort will be undefined. The purpose
            of `null` is to do faster metadata filter searches without care for
            relevancy. Cost per query is unchanged.
        k:
          type: integer
          title: K
          description: >-
            The number of documents to return. If there are not enough documents
            matching your filters, then fewer may be returned. This number must
            be between 1 and 2048, inclusive.
        filter:
          anyOf:
            - $ref: '#/components/schemas/StrJson'
            - type: 'null'
          description: >-
            The query filter to apply. Please read [Metadata
            Filtering](/metadata-filtering) for more information. If not
            provided, then all documents will be searched.
        include_metadata:
          type: boolean
          title: Include Metadata
          description: >-
            Whether or not to include the metadata in the top documents
            response. If not provided, then the default will be `False`.
          default: false
        reranker:
          anyOf:
            - type: string
            - type: 'null'
          title: Reranker
          description: >-
            The reranker to use after initial retrieval. The default is `null`.
            You can find available model ids along with more information at
            [/models/rerank](/api-reference/models/rerank).
        latency_mode:
          type: string
          enum:
            - low
            - high
          title: Latency Mode
          description: >-
            This option selects between our two latency modes. The higher
            latency mode takes longer, but can allow for more accurate
            responses. If desired, test both to customize your search experience
            for your particular use-case, or use the default of "low" and only
            swap if you need an additional improvement in search result quality.
          default: low
      type: object
      required:
        - collection_name
        - query
        - k
      title: TopDocumentsRequest
    TopDocumentsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/DocumentRetrievalResponse'
          type: array
          title: Results
      type: object
      required:
        - results
      title: TopDocumentsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StrJson:
      anyOf:
        - type: string
        - items:
            type: string
          type: array
        - items:
            $ref: '#/components/schemas/StrJson'
          type: array
        - additionalProperties:
            $ref: '#/components/schemas/StrJson'
          type: object
    DocumentRetrievalResponse:
      properties:
        path:
          type: string
          title: Path
          description: The path of the document.
        score:
          type: number
          title: Score
          description: The relevancy score assigned to this document.
        metadata:
          anyOf:
            - $ref: '#/components/schemas/DocumentMetadataJson'
            - type: 'null'
          description: >-
            The metadata for that document. Will be `None` if `include_metadata`
            is `False`.
        file_url:
          type: string
          title: File Url
          description: >-
            A URL to the document data, which can be used to download the raw
            document content or to display the document in frontend
            applications.


            NOTE: If a `/documents/update-document` call returned a new document
            id, then this url will be invalidated and must be retrieved again.
      type: object
      required:
        - path
        - score
        - metadata
        - file_url
      title: DocumentRetrievalResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    DocumentMetadataJson:
      additionalProperties:
        anyOf:
          - type: string
          - items:
              type: string
            type: array
      type: object
  securitySchemes:
    HTTPBearer:
      type: http
      description: >-
        The `Authorization` header must be provided in the format `Bearer
        <your-api-key>`.


        You can get your API Key at the
        [Dashboard](https://dashboard.zeroentropy.dev/)!
      scheme: bearer

````