superdocs-app Approval API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Approval API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Approval
paths:
  /v1/chat/{session_id}/approve:
    post:
      tags:
      - Approval
      summary: Approve or deny AI-proposed document changes one-by-one or in batch (HITL…
      description: 'Used with chat_async when approval_mode=''ask_every_time''. For each proposed change (with chunk_id and HTML diff), respond approved=true|false plus optional feedback for the AI to revise on. Approved changes apply atomically; denied changes are discarded; the AI may revise based on feedback in the next turn. Required for regulated workflows (legal, medical, compliance) where every AI edit must be reviewed before it touches the document. For single changes: set approved=true/false and optionally provide feedback. For batch decisions: provide a ''changes'' array with per-change decisions. After approval, the job resumes processing and eventually reaches status=completed.'
      operationId: approve_change
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ApprovalRequest:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Job ID that is awaiting approval.
        change_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Change Id
          description: Specific change to approve/deny (for individual decisions). Get change IDs from the job's pending_changes.
        approved:
          type: boolean
          title: Approved
          description: Whether to approve (true) or deny (false) the change.
        feedback:
          anyOf:
          - type: string
          - type: 'null'
          title: Feedback
          description: Optional feedback explaining why a change was denied. Helps the AI adjust future suggestions.
        changes:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Changes
          description: 'Batch decisions: array of {change_id, approved, feedback} objects. Use for ''Accept All'' or ''Deny All''.'
      type: object
      required:
      - job_id
      - approved
      title: ApprovalRequest
      description: Approve or deny proposed AI document changes.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer