openapi: 3.1.0
info:
  title: Credentially Public Compliance-packages Document Auto-fill API
  description: Public API Proxy with Rate Limiting and Audit
  version: 2.0.0
servers:
- url: https://app.credentially.io/gateway
  description: Generated server url
tags:
- name: Document Auto-fill
  description: Automated document data extraction and validation endpoints
paths:
  /api/documents/auto-fill/process:
    post:
      tags:
      - Document Auto-fill
      summary: Process and auto-fill fields from a new document
      description: 'Processes a newly uploaded file and returns extracted fields, validation outcome, and OCR metadata.


        **Rate Limit:** `shared-intensive-write-limit` (25 req / 1s)'
      operationId: autoFillProcess
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/AutoFillProcessDocumentRequest'
                file:
                  type: string
                  format: binary
              required:
              - file
              - request
      responses:
        '200':
          description: Document processed and fields extracted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoFillDocumentResponse'
        '400':
          description: Invalid request data
        '413':
          description: File size exceeds limit
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
  /api/documents/auto-fill/existing:
    post:
      tags:
      - Document Auto-fill
      summary: Auto-fill fields from an existing document
      description: 'Extracts structured field values from an existing stored document using your target schema.


        **Rate Limit:** `shared-intensive-write-limit` (25 req / 1s)'
      operationId: autoFillExisting
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoFillExistingDocumentRequest'
        required: true
      responses:
        '200':
          description: Field auto-filled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoFillDocumentResponse'
        '400':
          description: Invalid request data
        '404':
          description: Document not found
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
components:
  schemas:
    ExtractionMetadata:
      type: object
      description: Extraction metadata
      properties:
        confidence:
          type: number
          format: float
          description: Overall confidence score
          example: 0.98
        sourceFiles:
          type: array
          description: Source file identifiers used for extraction
          items:
            type: string
    AutoFillDocumentResponse:
      type: object
      description: Auto-fill response with extracted data
      properties:
        data:
          type: object
          additionalProperties: {}
          description: Extracted field values
        metadata:
          $ref: '#/components/schemas/ExtractionMetadata'
          description: Metadata about the extraction process
        validity:
          type: boolean
          description: Overall validity of the processed document. Can be null when not evaluated
        validationReason:
          type: string
          description: Explanation for the current validity result
        ocrExtraData:
          type: object
          additionalProperties: {}
          description: Additional OCR data extracted from the document
    AutoFillProcessDocumentRequest:
      type: object
      description: Request to process and auto-fill fields from a new document file
      properties:
        targetSchema:
          $ref: '#/components/schemas/TargetSchema'
          description: Schema defining fields to extract
        knownFields:
          type: object
          additionalProperties:
            type: string
          description: Pre-verified key-value pairs to anchor extraction
        promptMetadata:
          type: string
          description: Additional contextual instructions for extraction
        employeePublicId:
          type: string
          description: Employee public identifier
          example: staff-123
          minLength: 1
        uploaderId:
          type: string
          description: Uploader identifier
          example: uploader-456
        documentTypes:
          type: array
          description: List of document types to assist classification
          items:
            $ref: '#/components/schemas/DocumentTypeDefinition'
        customValidation:
          type: string
          description: Optional additional validation instructions applied after OCR and classification
      required:
      - employeePublicId
      - targetSchema
    AutoFillExistingDocumentRequest:
      type: object
      description: Request to auto-fill fields from existing document data
      properties:
        targetSchema:
          $ref: '#/components/schemas/TargetSchema'
          description: Schema defining fields to extract
        knownFields:
          type: object
          additionalProperties:
            type: string
          description: Pre-verified key-value pairs to anchor extraction
        promptMetadata:
          type: string
          description: Additional contextual instructions for extraction
        publicFileId:
          type: string
          description: Target document identifier
          example: a7263fea-4ee0-4cf8-b920-e48314dbee82
          minLength: 1
        customValidation:
          type: string
          description: Additional custom validation instructions evaluated after OCR
      required:
      - publicFileId
      - targetSchema
    FieldDefinition:
      type: object
      description: Individual field definition
      properties:
        name:
          type: string
          description: Field name
          example: license_id
          minLength: 1
        type:
          type: string
          description: Field type
          enum:
          - string
          - date
          - number
          - boolean
          - dictionary
          example: string
          minLength: 1
        format:
          type: string
          description: Format specification (e.g., YYYY-MM-DD for dates)
          example: YYYY-MM-DD
        description:
          type: string
          description: Additional description to guide extraction
        values:
          type: array
          description: Dictionary values, used when type is dictionary
          items:
            type: string
        hasOtherValue:
          type: boolean
          description: Indicates if values outside the list are allowed
      required:
      - name
      - type
    TargetSchema:
      type: object
      description: Target schema specification
      properties:
        fields:
          type: array
          description: List of fields to extract
          items:
            $ref: '#/components/schemas/FieldDefinition'
          minItems: 1
      required:
      - fields
    DocumentTypeDefinition:
      type: object
      description: Document type definition for classification
      properties:
        key:
          type: string
          description: Document type key
          example: DRIVER_LICENSE
          minLength: 1
        description:
          type: string
          description: Document type description
          example: Driver's license from any US state
      required:
      - key
  securitySchemes:
    bearer-key:
      type: http
      scheme: bearer
      bearerFormat: JWT