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.
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.