openapi: 3.2.0
info:
  title: CallidusAI Document Drafting API
  description: Callidus AI backend API
  version: 0.1.0
tags:
- name: Document Drafting
paths:
  /platform/drafts/document-types:
    get:
      tags:
      - Document Drafting
      summary: List Document Types
      description: Return the list of available document types and their supported jurisdictions.
      operationId: list_document_types_platform_drafts_document_types_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTypesResponse'
  /platform/matters/{matter_id}/drafts/schema:
    get:
      tags:
      - Document Drafting
      summary: Get Document Schema
      description: Return the full element/field schema for a document type — no draft created.
      operationId: get_document_schema_platform_matters__matter_id__drafts_schema_get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: document_type
        in: query
        required: true
        schema:
          type: string
          description: Key from DOCUMENT_REGISTRY
          title: Document Type
        description: Key from DOCUMENT_REGISTRY
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSchemaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts:
    post:
      tags:
      - Document Drafting
      summary: Create Draft
      description: Create a new draft — resolves all elements and returns full payload.
      operationId: create_draft_platform_matters__matter_id__drafts_post
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDraftPayload'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Document Drafting
      summary: List Drafts
      operationId: list_drafts_platform_matters__matter_id__drafts_get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 5
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__modules__matters__drafting__schemas__draft__DraftListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts/enrichment-status:
    get:
      tags:
      - Document Drafting
      summary: Batch Enrichment Status
      description: Batch poll Doc Agent enrichment status for one or more drafts.
      operationId: batch_enrichment_status_platform_matters__matter_id__drafts_enrichment_status_get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_ids
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated draft ids (max 50). Drafts not in this matter or not in the supplied list are silently dropped.
          title: Draft Ids
        description: Comma-separated draft ids (max 50). Drafts not in this matter or not in the supplied list are silently dropped.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftEnrichmentStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts/{draft_id}:
    get:
      tags:
      - Document Drafting
      summary: Get Draft
      operationId: get_draft_platform_matters__matter_id__drafts__draft_id__get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDraftPayload'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Document Drafting
      summary: Save Draft
      description: Full snapshot overwrite — replaces all elements.
      operationId: save_draft_platform_matters__matter_id__drafts__draft_id__put
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/app__modules__matters__drafting__schemas__draft__SaveDraftRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDraftPayload'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Document Drafting
      summary: Delete Draft
      description: Delete a draft record. The associated DocHub document (if any) is left intact.
      operationId: delete_draft_platform_matters__matter_id__drafts__draft_id__delete
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts/{draft_id}/elements/{element_id}:
    patch:
      tags:
      - Document Drafting
      summary: Patch Element
      description: Incremental Q&A save — replaces sections for one element only.
      operationId: patch_element_platform_matters__matter_id__drafts__draft_id__elements__element_id__patch
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      - name: element_id
        in: path
        required: true
        schema:
          type: string
          title: Element Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchElementRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDraftPayload'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts/{draft_id}/generate:
    post:
      tags:
      - Document Drafting
      summary: Generate Document
      description: 'Render the draft to .docx, upload to DocHub, return doc_id.


        Also kicks off the Doc Agent enrichment workflow (cancelling any

        in-flight enrichment for this draft first). Enrichment runs in the

        background; the response includes the running ``enrichment_status`` so

        the caller can poll for completion.'
      operationId: generate_document_platform_matters__matter_id__drafts__draft_id__generate_post
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/GenerateDocumentRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateDraftResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/drafts/{draft_id}/enrichment/retry:
    post:
      tags:
      - Document Drafting
      summary: Retry Enrichment
      description: 'Re-run Doc Agent enrichment against the existing source ``doc_id``.


        Cancels any in-flight enrichment for this draft, clears the prior

        ``enriched_doc_id``, and starts a fresh workflow. Returns the new

        ``enrichment_status`` blob so the caller can begin polling immediately.'
      operationId: retry_enrichment_platform_matters__matter_id__drafts__draft_id__enrichment_retry_post
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          title: Draft Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftEnrichmentEntry'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/elements/{element_id}/populate:
    get:
      tags:
      - Document Drafting
      summary: Populate Element
      description: Re-populate a single element from source data, a prior draft, or blank.
      operationId: populate_element_platform_matters__matter_id__elements__element_id__populate_get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: element_id
        in: path
        required: true
        schema:
          type: string
          title: Element Id
      - name: origin
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/DataOrigin'
          default: source
      - name: dataset_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Forensic dataset ID (required when origin=source)
          title: Dataset Id
        description: Forensic dataset ID (required when origin=source)
      - name: source_draft_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Draft Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulateElementResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /platform/matters/{matter_id}/elements/{element_id}/available-drafts:
    get:
      tags:
      - Document Drafting
      summary: Available Drafts For Element
      description: List drafts for this matter that have data for the requested element.
      operationId: available_drafts_for_element_platform_matters__matter_id__elements__element_id__available_drafts_get
      parameters:
      - name: matter_id
        in: path
        required: true
        schema:
          type: string
          title: Matter Id
      - name: element_id
        in: path
        required: true
        schema:
          type: string
          title: Element Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableDraftEntry'
                title: Response Available Drafts For Element Platform Matters  Matter Id  Elements  Element Id  Available Drafts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DocumentSchemaResponse:
      properties:
        document_type:
          type: string
          title: Document Type
        practice_area:
          type: string
          title: Practice Area
        elements:
          items:
            $ref: '#/components/schemas/ElementSchemaEntry'
          type: array
          title: Elements
      type: object
      required:
      - document_type
      - practice_area
      - elements
      title: DocumentSchemaResponse
    AvailableDraftEntry:
      properties:
        draft_id:
          type: string
          title: Draft Id
        label:
          type: string
          title: Label
        item_count:
          type: integer
          title: Item Count
      type: object
      required:
      - draft_id
      - label
      - item_count
      title: AvailableDraftEntry
    DocumentTypeEntry:
      properties:
        document_type:
          type: string
          title: Document Type
        practice_area:
          type: string
          title: Practice Area
        label:
          type: string
          title: Label
        supported_jurisdictions:
          items:
            $ref: '#/components/schemas/JurisdictionOption'
          type: array
          title: Supported Jurisdictions
      type: object
      required:
      - document_type
      - practice_area
      - label
      - supported_jurisdictions
      title: DocumentTypeEntry
    GenerateDocumentRequest:
      properties:
        matter_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Matter Name
      type: object
      title: GenerateDocumentRequest
    PatchElementRequest:
      properties:
        sections:
          items:
            $ref: '#/components/schemas/FormSection'
          type: array
          title: Sections
      type: object
      required:
      - sections
      title: PatchElementRequest
      description: Incremental update — replaces sections for a single element.
    GenerateDraftResponse:
      properties:
        draft_id:
          type: string
          title: Draft Id
        doc_id:
          type: string
          format: uuid
          title: Doc Id
        status:
          $ref: '#/components/schemas/DraftStatus'
          default: final
        enriched_doc_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Enriched Doc Id
        enrichment_status:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Enrichment Status
        fallback_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Fallback Note
      type: object
      required:
      - draft_id
      - doc_id
      title: GenerateDraftResponse
    DataSource:
      type: string
      enum:
      - forensic_analysis
      - tax_documents
      - user_input
      - user_override
      - discovery
      title: DataSource
    FormField:
      properties:
        key:
          type: string
          title: Key
        value:
          title: Value
        source:
          anyOf:
          - $ref: '#/components/schemas/DataSource'
          - type: 'null'
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        source_document_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Document Id
        widget:
          $ref: '#/components/schemas/UIWidget'
        label:
          type: string
          title: Label
        order:
          type: integer
          title: Order
        required:
          type: boolean
          title: Required
          default: true
        help_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Help Text
        placeholder:
          anyOf:
          - type: string
          - type: 'null'
          title: Placeholder
        options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Options
        visible_when:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Visible When
        group:
          anyOf:
          - type: string
          - type: 'null'
          title: Group
        show_if:
          anyOf:
          - type: string
          - type: 'null'
          title: Show If
        hidden:
          type: boolean
          title: Hidden
          default: false
      type: object
      required:
      - key
      - widget
      - label
      - order
      title: FormField
      description: 'One field: its UI definition merged with its current value.'
    PopulateElementResponse:
      properties:
        element_id:
          type: string
          title: Element Id
        sections:
          items: {}
          type: array
          title: Sections
        field_schema:
          items: {}
          type: array
          title: Field Schema
      type: object
      required:
      - element_id
      - sections
      - field_schema
      title: PopulateElementResponse
    DataOrigin:
      type: string
      enum:
      - source
      - draft
      - blank
      title: DataOrigin
    ElementForm:
      properties:
        element_id:
          type: string
          title: Element Id
        label:
          type: string
          title: Label
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        repeatable:
          type: boolean
          title: Repeatable
          default: false
        seed_locked:
          type: boolean
          title: Seed Locked
          default: false
        sections:
          items:
            $ref: '#/components/schemas/FormSection'
          type: array
          title: Sections
        field_schema:
          items:
            $ref: '#/components/schemas/FormField'
          type: array
          title: Field Schema
      type: object
      required:
      - element_id
      - label
      - sections
      - field_schema
      title: ElementForm
      description: One element ready to render in the UI.
    DraftStatus:
      type: string
      enum:
      - not_started
      - in_progress
      - complete
      - generating
      - final
      title: DraftStatus
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    app__modules__matters__drafting__schemas__draft__SaveDraftRequest:
      properties:
        elements:
          items:
            $ref: '#/components/schemas/ElementForm'
          type: array
          title: Elements
      type: object
      required:
      - elements
      title: SaveDraftRequest
      description: Full payload update — overwrites the entire form snapshot.
    DocumentDraftPayload:
      properties:
        draft_id:
          type: string
          title: Draft Id
        matter_id:
          type: string
          title: Matter Id
        document_type:
          type: string
          title: Document Type
        practice_area:
          type: string
          title: Practice Area
        jurisdiction:
          type: string
          title: Jurisdiction
        status:
          $ref: '#/components/schemas/DraftStatus'
        elements:
          items:
            $ref: '#/components/schemas/ElementForm'
          type: array
          title: Elements
        fields_filled:
          type: integer
          title: Fields Filled
          default: 0
        fields_total:
          type: integer
          title: Fields Total
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        jurisdiction_requirements:
          additionalProperties:
            type: boolean
          type: object
          title: Jurisdiction Requirements
      type: object
      required:
      - draft_id
      - matter_id
      - document_type
      - practice_area
      - jurisdiction
      - status
      - elements
      - created_at
      - updated_at
      title: DocumentDraftPayload
      description: 'Full form payload returned by create_draft and get_draft endpoints.


        This is also what gets stored verbatim in the form_snapshot JSONB column.

        jurisdiction_requirements contains the active CourtRequirements flags so the

        UI can evaluate each FormField''s show_if condition without a separate request.'
    FormSection:
      properties:
        fields:
          items:
            $ref: '#/components/schemas/FormField'
          type: array
          title: Fields
      type: object
      required:
      - fields
      title: FormSection
      description: A repeatable group — one bank account, one vehicle, one child, etc.
    app__modules__matters__drafting__schemas__draft__DraftListItem:
      properties:
        draft_id:
          type: string
          title: Draft Id
        document_type:
          type: string
          title: Document Type
        practice_area:
          type: string
          title: Practice Area
        jurisdiction:
          type: string
          title: Jurisdiction
        status:
          $ref: '#/components/schemas/DraftStatus'
        doc_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Doc Id
        doc_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Doc Name
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
        enriched_doc_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Enriched Doc Id
        enriched_doc_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Enriched Doc Name
        enriched_download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Enriched Download Url
        enrichment_status:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Enrichment Status
        enriched_with_template:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Enriched With Template
        fields_filled:
          type: integer
          title: Fields Filled
        fields_total:
          type: integer
          title: Fields Total
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - draft_id
      - document_type
      - practice_area
      - jurisdiction
      - status
      - doc_id
      - fields_filled
      - fields_total
      - created_at
      - updated_at
      title: DraftListItem
    CreateDraftRequest:
      properties:
        document_type:
          type: string
          title: Document Type
          description: Key from DOCUMENT_REGISTRY, e.g. 'marital_settlement_agreement'
        jurisdiction:
          anyOf:
          - type: string
          - type: 'null'
          title: Jurisdiction
          description: State abbreviation, e.g. 'NH'. Omit to auto-derive from the matter's forensic profile.
        dataset_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dataset Id
          description: Forensic dataset ID; auto-resolved from matter if omitted
      type: object
      required:
      - document_type
      title: CreateDraftRequest
    DocumentTypesResponse:
      properties:
        document_types:
          items:
            $ref: '#/components/schemas/DocumentTypeEntry'
          type: array
          title: Document Types
      type: object
      required:
      - document_types
      title: DocumentTypesResponse
    UIWidget:
      type: string
      enum:
      - text
      - currency
      - date
      - select
      - multi_select
      - checkbox
      - textarea
      - masked
      - number
      - percent
      title: UIWidget
    DraftEnrichmentStatusResponse:
      properties:
        drafts:
          additionalProperties:
            $ref: '#/components/schemas/DraftEnrichmentEntry'
          type: object
          title: Drafts
      type: object
      required:
      - drafts
      title: DraftEnrichmentStatusResponse
      description: Batch poll response keyed by draft id.
    app__modules__matters__drafting__schemas__draft__DraftListResponse:
      properties:
        drafts:
          items:
            $ref: '#/components/schemas/app__modules__matters__drafting__schemas__draft__DraftListItem'
          type: array
          title: Drafts
        total:
          type: integer
          title: Total
      type: object
      required:
      - drafts
      - total
      title: DraftListResponse
    JurisdictionOption:
      properties:
        code:
          type: string
          title: Code
        display_name:
          type: string
          title: Display Name
      type: object
      required:
      - code
      - display_name
      title: JurisdictionOption
    DraftEnrichmentEntry:
      properties:
        draft_id:
          type: string
          title: Draft Id
        doc_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Doc Id
        enriched_doc_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Enriched Doc Id
        enrichment_status:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Enrichment Status
        enriched_with_template:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Enriched With Template
      type: object
      required:
      - draft_id
      - doc_id
      - enriched_doc_id
      - enrichment_status
      title: DraftEnrichmentEntry
      description: Per-draft entry in the batch enrichment-status polling response.
    ElementSchemaEntry:
      properties:
        element_id:
          type: string
          title: Element Id
        label:
          type: string
          title: Label
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        repeatable:
          type: boolean
          title: Repeatable
        has_resolver:
          type: boolean
          title: Has Resolver
        field_schema:
          items: {}
          type: array
          title: Field Schema
      type: object
      required:
      - element_id
      - label
      - description
      - repeatable
      - has_resolver
      - field_schema
      title: ElementSchemaEntry
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError