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:
    namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
      description: Document namespace identifier
    doctype:
      name: doctype
      in: path
      required: true
      schema:
        type: string
      description: Schema document type name
    Condition:
      name: condition
      in: query
      schema:
        type: string
      description: Test-and-set condition selection expression.
    Cluster:
      name: cluster
      in: query
      schema:
        type: string
      description: Content cluster name. Required for visit and bulk operations.
    Namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
      description: Document namespace (a multi-tenant grouping segment).
    timeout:
      name: timeout
      in: query
      schema:
        type: string
      description: Operation timeout, e.g. "5s"
    Route:
      name: route
      in: query
      schema:
        type: string
      description: Document API route name for advanced routing.
    Create:
      name: create
      in: query
      schema:
        type: boolean
      description: If true, create the document when missing on update (upsert).
    DocumentId:
      name: documentId
      in: path
      required: true
      schema:
        type: string
      description: Document id within the namespace and type.
    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`.
    create:
      name: create
      in: query
      schema:
        type: boolean
      description: Allow upsert behavior (create document if absent)
    Continuation:
      name: continuation
      in: query
      schema:
        type: string
      description: Continuation token from a prior visit response.
    Selection:
      name: selection
      in: query
      schema:
        type: string
      description: Vespa document selection expression.
    WantedDocumentCount:
      name: wantedDocumentCount
      in: query
      schema:
        type: integer
      description: Target number of documents to return per visit batch.
    DocumentType:
      name: documentType
      in: path
      required: true
      schema:
        type: string
      description: Document type as declared in the Vespa application schema.
    docid:
      name: docid
      in: path
      required: true
      schema:
        type: string
      description: Unique document identifier within the namespace
  schemas:
    DocumentBody:
      type: object
      required:
      - fields
      properties:
        fields:
          type: object
          additionalProperties: true
          description: Document field values keyed by schema field name.
    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
    DocumentUpdate:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
    DocumentPut:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
    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_2:
      type: object
      properties:
        pathId:
          type: string
        id:
          type: string
        fields:
          type: object
          additionalProperties: true
    Document:
      type: object
      properties:
        id:
          type: string
        fields:
          type: object
          additionalProperties: true
  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