openapi: 3.0.3
info:
  title: Vespa Query API
  description: |
    The Vespa Query (Search) API executes structured and vector queries against a Vespa application
    using YQL (Vespa Query Language). It supports text search with BM25, approximate-nearest-neighbor
    vector search over HNSW indexes, hybrid search, machine-learned ranking with multi-phase rank
    profiles, grouping/aggregation, pagination, result presentation, and tracing.

    The Query API can be called as a GET with query-string parameters or as a POST with a JSON body
    for complex query expressions. Responses are returned as JSON (default), CBOR, or XML.
  version: '1.0'
  contact:
    name: Vespa
    url: https://vespa.ai
  license:
    name: Apache 2.0
    url: https://github.com/vespa-engine/vespa/blob/master/LICENSE
servers:
  - url: http://localhost:8080
    description: Default local Vespa container endpoint
  - url: https://{endpoint}.vespa-cloud.com
    description: Vespa Cloud application endpoint
    variables:
      endpoint:
        default: example
        description: Vespa Cloud application endpoint hostname prefix
paths:
  /search/:
    get:
      operationId: queryGet
      summary: Execute Query Via GET
      description: Execute a Vespa query using URL-encoded query-string parameters.
      tags:
        - Query
      parameters:
        - name: yql
          in: query
          description: YQL query expression, e.g. `select * from sources * where userQuery()`.
          required: false
          schema:
            type: string
        - name: query
          in: query
          description: Simple user query string passed to the query parser.
          required: false
          schema:
            type: string
        - name: hits
          in: query
          description: Maximum number of hits to return.
          required: false
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Number of hits to skip for pagination.
          required: false
          schema:
            type: integer
            default: 0
        - name: ranking.profile
          in: query
          description: Name of the rank profile to use for scoring.
          required: false
          schema:
            type: string
        - name: timeout
          in: query
          description: Query timeout, e.g. `500ms` or `5s`.
          required: false
          schema:
            type: string
        - name: trace.level
          in: query
          description: Trace verbosity level for debugging.
          required: false
          schema:
            type: integer
        - name: presentation.format
          in: query
          description: Response format. One of `json`, `cbor`, or `xml`.
          required: false
          schema:
            type: string
            enum: [json, cbor, xml]
            default: json
      responses:
        '200':
          description: Successful query result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Bad request (invalid YQL or parameters).
        '408':
          description: Query timed out.
        '500':
          description: Server error.
        '503':
          description: Service unavailable.
        '504':
          description: Gateway timeout.
    post:
      operationId: queryPost
      summary: Execute Query Via POST
      description: Execute a Vespa query whose parameters are provided as a JSON body. Equivalent to
        GET but allows longer YQL expressions and complex grouping/ranking inputs.
      tags:
        - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Successful query result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Bad request.
        '408':
          description: Query timed out.
        '500':
          description: Server error.
components:
  schemas:
    QueryRequest:
      type: object
      properties:
        yql:
          type: string
          description: YQL query expression.
        query:
          type: string
          description: Simple user query string.
        hits:
          type: integer
          default: 10
        offset:
          type: integer
          default: 0
        ranking:
          type: object
          description: Ranking configuration, including profile and feature inputs.
          additionalProperties: true
        presentation:
          type: object
          description: Presentation options such as summary class and bolding.
          additionalProperties: true
        model:
          type: object
          description: Query model parameters (defaultIndex, restrict, sources, type, language).
          additionalProperties: true
        select:
          type: string
          description: Grouping / aggregation specification.
        timeout:
          type: string
        trace:
          type: object
          additionalProperties: true
    QueryResult:
      type: object
      properties:
        root:
          $ref: '#/components/schemas/QueryRoot'
    QueryRoot:
      type: object
      properties:
        id:
          type: string
        relevance:
          type: number
        fields:
          type: object
          additionalProperties: true
        coverage:
          $ref: '#/components/schemas/Coverage'
        children:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
    Hit:
      type: object
      properties:
        id:
          type: string
        relevance:
          type: number
        source:
          type: string
        fields:
          type: object
          additionalProperties: true
    Coverage:
      type: object
      properties:
        coverage:
          type: integer
        documents:
          type: integer
        full:
          type: boolean
        nodes:
          type: integer
        results:
          type: integer
        resultsFull:
          type: integer
  securitySchemes:
    mtls:
      type: http
      scheme: bearer
      description: Vespa Cloud endpoints typically use mTLS with a client data-plane certificate.