Vespa

Vespa Documents API

Single-document GET, POST, PUT, DELETE operations

GitHub OpenAPI

Operations 11

GET /{namespace}/{doctype}/docid/{docid} Get a single document #
POST /{namespace}/{doctype}/docid/{docid} Put (create or overwrite) a document #
PUT /{namespace}/{doctype}/docid/{docid} Update (partial update) a document #
DELETE /{namespace}/{doctype}/docid/{docid} Delete a document #
GET /document/v1/ Visit Documents Across Cluster #
GET /document/v1/{namespace}/{documentType}/docid/{documentId} Get Document By Id #
POST /document/v1/{namespace}/{documentType}/docid/{documentId} Put Document #
PUT /document/v1/{namespace}/{documentType}/docid/{documentId} Update Document #
DELETE /document/v1/{namespace}/{documentType}/docid/{documentId} Remove Document #
GET /document/v1/{namespace}/{documentType}/docid Visit Documents Of A Type #
DELETE /document/v1/{namespace}/{documentType}/docid Delete Documents Matching Selection #

Documentation

📖
Documentation
https://docs.vespa.ai/en/reference/document-v1-api-reference.html
📖
Documentation
https://docs.vespa.ai/en/writing/document-v1-api-guide.html
📖
Documentation
https://docs.vespa.ai/en/reads-and-writes.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/vespa-ai/refs/heads/main/openapi/vespa-ai-documents-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/vespa-ai-documents-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

vespa-ai-documents-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Vespa Ai Documents API
  version: '1.0'
  description: 'Operations tagged Documents across 2 of this provider''s published API definitions: vespa-ai-documents-api-openapi.yml, vespa-document-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{vespa_endpoint}/document/v1
  description: Vespa container document API base URL
  variables:
    vespa_endpoint:
      default: localhost:8080
      description: Host:port of the Vespa container exposing /document/v1
- 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: Documents
  description: Single-document GET, POST, PUT, DELETE operations
paths:
  /{namespace}/{doctype}/docid/{docid}:
    parameters:
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/doctype'
    - $ref: '#/components/parameters/docid'
    servers:
    - url: http://{vespa_endpoint}/document/v1
      description: Vespa container document API base URL
      variables:
        vespa_endpoint:
          default: localhost:8080
          description: Host:port of the Vespa container exposing /document/v1
    get:
      tags:
      - Documents
      summary: Get a single document
      operationId: getDocument
      parameters:
      - $ref: '#/components/parameters/timeout'
      responses:
        '200':
          description: Document found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          description: Document not found
      security:
      - mtls: []
    post:
      tags:
      - Documents
      summary: Put (create or overwrite) a document
      operationId: putDocument
      parameters:
      - $ref: '#/components/parameters/create'
      - $ref: '#/components/parameters/timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentPut'
      responses:
        '200':
          description: Document written
      security:
      - mtls: []
    put:
      tags:
      - Documents
      summary: Update (partial update) a document
      operationId: updateDocument
      parameters:
      - $ref: '#/components/parameters/create'
      - $ref: '#/components/parameters/timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdate'
      responses:
        '200':
          description: Document updated
      security:
      - mtls: []
    delete:
      tags:
      - Documents
      summary: Delete a document
      operationId: deleteDocument
      parameters:
      - $ref: '#/components/parameters/timeout'
      responses:
        '200':
          description: Document deleted
      security:
      - mtls: []
  /document/v1/:
    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
    get:
      operationId: visitAllDocuments
      summary: Visit Documents Across Cluster
      description: Visit (stream) documents from a content cluster. Requires the `cluster` query parameter.
      tags:
      - Documents
      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'
    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
    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_2'
        '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'
    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
    get:
      operationId: visitDocumentsByType
      summary: Visit Documents Of A Type
      description: Visit (stream) documents of the given namespace and document type.
      tags:
      - Documents
      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
      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:
    DocumentType:
      name: documentType
      in: path
      required: true
      schema:
        type: string
      description: Document type as declared in the Vespa application schema.
    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.
    DocumentId:
      name: documentId
      in: path
      required: true
      schema:
        type: string
      description: Document id within the namespace and type.
    Timeout:
      name: timeout
      in: query
      schema:
        type: string
      description: Request timeout, e.g. `5s`.
    Route:
      name: route
      in: query
      schema:
        type: string
      description: Document API route name for advanced routing.
    Namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
      description: Document namespace (a multi-tenant grouping segment).
    namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
      description: Document namespace identifier
    Condition:
      name: condition
      in: query
      schema:
        type: string
      description: Test-and-set condition selection expression.
    WantedDocumentCount:
      name: wantedDocumentCount
      in: query
      schema:
        type: integer
      description: Target number of documents to return per visit batch.
    create:
      name: create
      in: query
      schema:
        type: boolean
      description: Allow upsert behavior (create document if absent)
    Cluster:
      name: cluster
      in: query
      schema:
        type: string
      description: Content cluster name. Required for visit and bulk operations.
    docid:
      name: docid
      in: path
      required: true
      schema:
        type: string
      description: Unique document identifier within the namespace
    Stream:
      name: stream
      in: query
      schema:
        type: boolean
      description: When true, stream responses as JSON Lines.
    timeout:
      name: timeout
      in: query
      schema:
        type: string
      description: Operation timeout, e.g. "5s"
    FieldSet:
      name: fieldSet
      in: query
      schema:
        type: string
      description: Field set name controlling which document fields are returned.
    doctype:
      name: doctype
      in: path
      required: true
      schema:
        type: string
      description: Schema document type name
    Create:
      name: create
      in: query
      schema:
        type: boolean
      description: If true, create the document when missing on update (upsert).
  schemas:
    DocumentPut:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
    Document:
      type: object
      properties:
        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_2'
        documentCount:
          type: integer
        continuation:
          type: string
        message:
          type: string
    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.
    DocumentUpdate:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
    Document_2:
      type: object
      properties:
        pathId:
          type: string
        id:
          type: string
        fields:
          type: object
          additionalProperties: true
    DocumentBody:
      type: object
      required:
      - fields
      properties:
        fields:
          type: object
          additionalProperties: true
          description: Document field values keyed by schema field name.
  securitySchemes:
    mtls:
      type: mutualTLS
      description: Client certificate authentication (Vespa enforces mTLS when configured)
x-refined-from:
- vespa-ai-documents-api-openapi.yml
- vespa-document-api-openapi.yml