openapi: 3.0.1
info:
  title: Zuva DocAI API
  description: >-
    The Zuva DocAI API is a RESTful contract and document AI API for extracting
    structured data from unstructured documents. It provides asynchronous file
    submission, OCR, field extraction across 1,400+ pre-built fields, multi-level
    document classification across 220+ document types, language detection, and a
    searchable fields catalog. All requests are authenticated with a Bearer API
    token and served from regional hosts (US and EU).
  termsOfService: https://zuva.ai/terms/zuva/
  contact:
    name: Zuva Support
    url: https://zuva.ai/
  version: '2.0'
servers:
  - url: https://{region}.app.zuva.ai/api/v2
    description: Zuva DocAI regional API server
    variables:
      region:
        default: us
        description: Deployment region for the Zuva DocAI API.
        enum:
          - us
          - eu
security:
  - bearerAuth: []
tags:
  - name: Files
    description: Upload and manage document files.
  - name: Field Extraction
    description: Extract field values from documents.
  - name: Classification
    description: Multi-level document classification.
  - name: OCR
    description: Optical character recognition.
  - name: Fields
    description: Field catalog management.
paths:
  /files:
    post:
      operationId: createFile
      tags:
        - Files
      summary: Upload a document file.
      description: >-
        Upload the binary content of a document to Zuva. Returns a file_id used
        by the OCR, extraction, and classification services.
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: File created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
    delete:
      operationId: deleteFiles
      tags:
        - Files
      summary: Delete multiple files.
      description: Delete multiple uploaded files by their file IDs.
      parameters:
        - name: file_ids
          in: query
          required: true
          description: Comma-separated list of file IDs to delete.
          schema:
            type: string
      responses:
        '204':
          description: Files deleted.
  /files/{file_id}:
    delete:
      operationId: deleteFile
      tags:
        - Files
      summary: Delete a single file.
      parameters:
        - $ref: '#/components/parameters/FileId'
      responses:
        '204':
          description: File deleted.
  /files/{file_id}/expiration:
    put:
      operationId: updateFileExpiration
      tags:
        - Files
      summary: Update a file's expiration.
      description: Update the retention period (expiration) of an uploaded file.
      parameters:
        - $ref: '#/components/parameters/FileId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                expiration:
                  type: string
                  format: date-time
                  description: New expiration timestamp for the file.
      responses:
        '200':
          description: Expiration updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
  /extraction:
    post:
      operationId: createExtraction
      tags:
        - Field Extraction
      summary: Create field extraction requests.
      description: >-
        Submit one or more files and field IDs to extract. Accepts up to 100
        file IDs and 100 field IDs per request. Returns one request per file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractionRequest'
      responses:
        '202':
          description: Extraction requests accepted and queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_ids:
                    type: array
                    items:
                      type: string
                  field_ids:
                    type: array
                    items:
                      type: string
                  status:
                    type: string
  /extractions:
    get:
      operationId: getExtractions
      tags:
        - Field Extraction
      summary: Query multiple extraction requests.
      parameters:
        - name: request_id
          in: query
          required: false
          description: Comma-separated list of extraction request IDs.
          schema:
            type: string
      responses:
        '200':
          description: Extraction request statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Request'
  /extraction/{request_id}:
    get:
      operationId: getExtraction
      tags:
        - Field Extraction
      summary: Retrieve an extraction request status.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Extraction request status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
  /extraction/{request_id}/results/text:
    get:
      operationId: getExtractionResultsText
      tags:
        - Field Extraction
      summary: Retrieve extraction text results.
      description: Fetch extracted field values with text spans and locations.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Extraction results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionResults'
  /mlc:
    post:
      operationId: createClassification
      tags:
        - Classification
      summary: Create a document classification request.
      description: >-
        Submit files to the multi-level classification (MLC) service, which
        classifies documents across 220+ document types and returns the
        document language and amendment status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file_ids
              properties:
                file_ids:
                  type: array
                  items:
                    type: string
      responses:
        '202':
          description: Classification requests accepted and queued.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClassificationResult'
  /mlcs:
    get:
      operationId: getClassifications
      tags:
        - Classification
      summary: Query multiple classification requests.
      parameters:
        - name: request_id
          in: query
          required: false
          description: Comma-separated list of classification request IDs.
          schema:
            type: string
      responses:
        '200':
          description: Classification request statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClassificationResult'
  /mlc/{request_id}:
    get:
      operationId: getClassification
      tags:
        - Classification
      summary: Retrieve classification status and results.
      description: >-
        Retrieve the classification result for a request, including the
        document type, detected language, and whether the document is an
        amendment.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Classification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationResult'
  /ocr:
    post:
      operationId: createOcr
      tags:
        - OCR
      summary: Create an OCR request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file_ids
              properties:
                file_ids:
                  type: array
                  items:
                    type: string
      responses:
        '202':
          description: OCR requests accepted and queued.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OcrResult'
  /ocrs:
    get:
      operationId: getOcrs
      tags:
        - OCR
      summary: Query multiple OCR requests.
      parameters:
        - name: request_id
          in: query
          required: false
          description: Comma-separated list of OCR request IDs.
          schema:
            type: string
      responses:
        '200':
          description: OCR request statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OcrResult'
  /ocr/{request_id}:
    get:
      operationId: getOcr
      tags:
        - OCR
      summary: Retrieve an OCR request status.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: OCR request status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
  /ocr/{request_id}/text:
    get:
      operationId: getOcrText
      tags:
        - OCR
      summary: Retrieve OCR extracted text.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Extracted text.
          content:
            text/plain:
              schema:
                type: string
  /ocr/{request_id}/images:
    get:
      operationId: getOcrImages
      tags:
        - OCR
      summary: Download all page images as a zip.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Zip archive of page PNG images.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /ocr/{request_id}/images/{page_number}:
    get:
      operationId: getOcrImagePage
      tags:
        - OCR
      summary: Download a single page image.
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - name: page_number
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: PNG image of the requested page.
          content:
            image/png:
              schema:
                type: string
                format: binary
  /ocr/{request_id}/layouts:
    get:
      operationId: getOcrLayouts
      tags:
        - OCR
      summary: Retrieve layout protobuf binary.
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Layout protobuf binary.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /fields:
    get:
      operationId: getFields
      tags:
        - Fields
      summary: List available fields.
      description: List all available extraction fields with their metadata.
      responses:
        '200':
          description: List of fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Field'
    post:
      operationId: createField
      tags:
        - Fields
      summary: Create a custom extraction field.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                field_name:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: Field created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
  /fields/{field_id}/metadata:
    get:
      operationId: getFieldMetadata
      tags:
        - Fields
      summary: Retrieve field metadata.
      parameters:
        - $ref: '#/components/parameters/FieldId'
      responses:
        '200':
          description: Field metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
    put:
      operationId: updateFieldMetadata
      tags:
        - Fields
      summary: Update field metadata.
      description: Update a field's name and description.
      parameters:
        - $ref: '#/components/parameters/FieldId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                field_name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: Field metadata updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Zuva API token passed in the Authorization header as
        `Authorization: Bearer <token>`.
  parameters:
    FileId:
      name: file_id
      in: path
      required: true
      description: The unique identifier of an uploaded file.
      schema:
        type: string
    RequestId:
      name: request_id
      in: path
      required: true
      description: The unique identifier of an asynchronous request.
      schema:
        type: string
    FieldId:
      name: field_id
      in: path
      required: true
      description: The unique identifier of a field.
      schema:
        type: string
  schemas:
    File:
      type: object
      properties:
        file_id:
          type: string
        expiration:
          type: string
          format: date-time
        attributes:
          type: array
          items:
            type: string
        size:
          type: integer
        permissions:
          type: array
          items:
            type: string
    ExtractionRequest:
      type: object
      required:
        - file_ids
        - field_ids
      properties:
        file_ids:
          type: array
          description: Up to 100 file IDs.
          items:
            type: string
        field_ids:
          type: array
          description: Up to 100 field IDs.
          items:
            type: string
        options:
          type: object
          properties:
            field_heuristics:
              type: array
              items:
                type: object
    Request:
      type: object
      properties:
        request_id:
          type: string
        file_id:
          type: string
        field_ids:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - complete
            - failed
    ExtractionResults:
      type: object
      properties:
        request_id:
          type: string
        file_id:
          type: string
        results:
          type: array
          items:
            type: object
            properties:
              field_id:
                type: string
              text:
                type: string
              spans:
                type: array
                items:
                  type: object
                  properties:
                    start:
                      type: integer
                    end:
                      type: integer
    ClassificationResult:
      type: object
      properties:
        request_id:
          type: string
        file_id:
          type: string
        status:
          type: string
        classification:
          type: string
        language:
          type: string
        is_amendment:
          type: boolean
    OcrResult:
      type: object
      properties:
        request_id:
          type: string
        file_id:
          type: string
        status:
          type: string
        page_count:
          type: integer
        character_count:
          type: integer
        scan_quality:
          type: string
        scan_score:
          type: number
    Field:
      type: object
      properties:
        field_id:
          type: string
        name:
          type: string
        description:
          type: string
        bias:
          type: number
        f_score:
          type: number
        precision:
          type: number
        recall:
          type: number
        is_custom:
          type: boolean