Vespa Query API

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
tags:
- name: Query
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:
    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
    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
    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.