Document Operation API

This document explains the JSON REST API for put, update, remove, get and visit operations to a Vespa cluster. It is not a high throughput API, but designed for ease of use. Read the introduction. To enable the API, add document-api in services.xml:


Document Format

The structure is based on the document format, but the document ID is moved to the request URI instead of the document itself. The document fields must match the search definition. A request looks like:

[PUT/POST/DELETE/GET]: [host]:[port]/document/v1/{namespace}/{document-type}/docid/[{user-specified}]
Documents can be grouped:
[PUT/POST/DELETE/GET]: [host]:[port]/document/v1/{namespace}/{document-type}/[group|number]/{group name or number value}/[{user-specified}]
Example, inserting a document:
POST: [host]:[port]/document/v1/music/music/docid/123

    "fields": {
        "songs": "Knockin on Heaven's Door; Mr. Tambourine Man",
        "title": "Best of Bob Dylan",
        "url": ""


Insert a new document, using HTTP POST. Optional parameters: condition and route.

$ curl -X POST --data-binary @document-1.json http://hostname:8080/document/v1/music/music/docid/1


Update a document, using HTTP PUT. Optional parameters: condition, create, and route.

$ curl -X PUT --data-binary @update.json http://hostname:8080/document/v1/music/music/docid/1


Delete a document, using HTTP DELETE. Optional parameters: condition and route.

$ curl -X DELETE http://hostname:8080/document/v1/music/music/docid/1


Get one or more documents, using HTTP GET:

$ curl http://hostname:8080/document/v1/music/music/docid/1
If docid is not specified, selection is supported and a set of documents is returned using visiting:
$ curl http://hostname:8080/document/v1/music/music/docid
Visit all documents for a group:
$ curl http://hostname:8080/document/v1/music/some-type-with-group/group/yellow/
A specific document in a group:
$ curl http://hostname:8080/document/v1/music/some-type-with-number/number/23/some_key
To visit larger sets, use continuation.


condition Requires that this condition is true, otherwise a 40x is returned. See conditional updates for details.
create true | false. If set to true, updates will create new document if not existing. See updates for more details on updates to non existing documents.
selection Select a set of documents using visiting - details in document selector language.
continuation When visiting, a continuation token is returned if the result set is large. Use the token in the continuation parameter (otherwise equal) to get the next set of documents.
route This is the route for document operations. Default value is 'default'. See routes