Vespa
Vespa Document API

The Vespa Document API (/document/v1) provides synchronous REST access to document operations against a Vespa content cluster. It supports Put, Get, Update (partial update with assign/add/remove operators), Remove, and Visit (streaming visit, copy, delete-where, update-where) over JSON or JSON Lines, with conditional writes, multi-tenant namespaces, field-set projection, time-window selection, and pagination via continuation tokens.
Vespa Document API is one of 8 APIs that Vespa publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.
Tagged areas include Documents, CRUD, Indexing, Data, and Streaming. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and 1 Naftiko capability spec.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.3
info:
  title: Vespa Document API
  description: |
    The Vespa Document API (`/document/v1`) provides synchronous REST access to document operations
    against a Vespa content cluster. It supports Put, Get, Update (partial update with assign/add/remove
    operators), Remove, and Visit (streaming visit, copy, delete-where, update-where) over JSON or
    JSON Lines, with conditional writes, multi-tenant namespaces, field-set projection, time-window
    selection, and pagination via continuation tokens.
  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:
  /document/v1/:
    get:
      operationId: visitAllDocuments
      summary: Visit Documents Across Cluster
      description: Visit (stream) documents from a content cluster. Requires the `cluster` query
        parameter.
      tags:
        - Documents
        - Visit
      parameters:
        - $ref: '#/components/parameters/Cluster'
        - $ref: '#/components/parameters/Selection'
        - $ref: '#/components/parameters/Continuation'
        - $ref: '#/components/parameters/WantedDocumentCount'
        - $ref: '#/components/parameters/Stream'
        - $ref: '#/components/parameters/FieldSet'
        - $ref: '#/components/parameters/Timeout'
      responses:
        '200':
          description: Visit result. JSON by default, JSON Lines when `Accept: application/jsonl`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitResponse'
            application/jsonl:
              schema:
                type: string
                description: Newline-separated JSON objects (put, remove, continuation, sessionStats).
        '400':
          description: Bad request.
        '429':
          description: Too many inflight requests.
  /document/v1/{namespace}/{documentType}/docid/{documentId}:
    parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/DocumentType'
      - $ref: '#/components/parameters/DocumentId'
    get:
      operationId: getDocument
      summary: Get Document By Id
      description: Retrieve a single document by its document id.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/FieldSet'
        - $ref: '#/components/parameters/Cluster'
        - $ref: '#/components/parameters/Timeout'
      responses:
        '200':
          description: Document found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          description: Document not found.
    post:
      operationId: putDocument
      summary: Put Document
      description: Create or overwrite a document with the given id.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/Condition'
        - $ref: '#/components/parameters/Route'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentBody'
      responses:
        '200':
          description: Document written successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentWriteResponse'
        '400':
          description: Bad request.
        '412':
          description: Test-and-set condition failed.
        '413':
          description: Payload too large.
    put:
      operationId: updateDocument
      summary: Update Document
      description: Apply a partial update to a document using assign / add / remove operators.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/Condition'
        - $ref: '#/components/parameters/Create'
        - $ref: '#/components/parameters/Route'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdateBody'
      responses:
        '200':
          description: Document updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentWriteResponse'
        '412':
          description: Test-and-set condition failed or document does not exist.
    delete:
      operationId: removeDocument
      summary: Remove Document
      description: Remove a document with the given id.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/Condition'
        - $ref: '#/components/parameters/Route'
        - $ref: '#/components/parameters/Timeout'
      responses:
        '200':
          description: Document removed successfully (or did not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentWriteResponse'
  /document/v1/{namespace}/{documentType}/docid:
    parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/DocumentType'
    get:
      operationId: visitDocumentsByType
      summary: Visit Documents Of A Type
      description: Visit (stream) documents of the given namespace and document type.
      tags:
        - Documents
        - Visit
      parameters:
        - $ref: '#/components/parameters/Selection'
        - $ref: '#/components/parameters/Continuation'
        - $ref: '#/components/parameters/WantedDocumentCount'
        - $ref: '#/components/parameters/Stream'
        - $ref: '#/components/parameters/FieldSet'
        - $ref: '#/components/parameters/Timeout'
        - $ref: '#/components/parameters/Cluster'
      responses:
        '200':
          description: Visit result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitResponse'
    delete:
      operationId: deleteWhere
      summary: Delete Documents Matching Selection
      description: Bulk-delete documents matching a Vespa selection expression. Requires `cluster`
        and `selection`.
      tags:
        - Documents
        - Visit
      parameters:
        - $ref: '#/components/parameters/Cluster'
        - $ref: '#/components/parameters/Selection'
        - $ref: '#/components/parameters/Timeout'
      responses:
        '200':
          description: Bulk delete completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitResponse'
components:
  parameters:
    Namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
      description: Document namespace (a multi-tenant grouping segment).
    DocumentType:
      name: documentType
      in: path
      required: true
      schema:
        type: string
      description: Document type as declared in the Vespa application schema.
    DocumentId:
      name: documentId
      in: path
      required: true
      schema:
        type: string
      description: Document id within the namespace and type.
    Cluster:
      name: cluster
      in: query
      schema:
        type: string
      description: Content cluster name. Required for visit and bulk operations.
    Selection:
      name: selection
      in: query
      schema:
        type: string
      description: Vespa document selection expression.
    Continuation:
      name: continuation
      in: query
      schema:
        type: string
      description: Continuation token from a prior visit response.
    WantedDocumentCount:
      name: wantedDocumentCount
      in: query
      schema:
        type: integer
      description: Target number of documents to return per visit batch.
    Stream:
      name: stream
      in: query
      schema:
        type: boolean
      description: When true, stream responses as JSON Lines.
    FieldSet:
      name: fieldSet
      in: query
      schema:
        type: string
      description: Field set name controlling which document fields are returned.
    Timeout:
      name: timeout
      in: query
      schema:
        type: string
      description: Request timeout, e.g. `5s`.
    Condition:
      name: condition
      in: query
      schema:
        type: string
      description: Test-and-set condition selection expression.
    Create:
      name: create
      in: query
      schema:
        type: boolean
      description: If true, create the document when missing on update (upsert).
    Route:
      name: route
      in: query
      schema:
        type: string
      description: Document API route name for advanced routing.
  schemas:
    DocumentBody:
      type: object
      required: [fields]
      properties:
        fields:
          type: object
          additionalProperties: true
          description: Document field values keyed by schema field name.
    DocumentUpdateBody:
      type: object
      required: [fields]
      properties:
        fields:
          type: object
          additionalProperties: true
          description: Update operators (assign, add, remove, increment, decrement, multiply, divide)
            keyed by field name.
    Document:
      type: object
      properties:
        pathId:
          type: string
        id:
          type: string
        fields:
          type: object
          additionalProperties: true
    DocumentWriteResponse:
      type: object
      properties:
        pathId:
          type: string
        id:
          type: string
        message:
          type: string
    VisitResponse:
      type: object
      properties:
        pathId:
          type: string
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        documentCount:
          type: integer
        continuation:
          type: string
        message:
          type: string
  securitySchemes:
    mtls:
      type: http
      scheme: bearer
      description: Vespa Cloud endpoints use mTLS with a client data-plane certificate.
Vespa Document API

Documentation

Specifications

Other Resources

OpenAPI Specification
