openapi: 3.0.3
info:
  title: Suki Form Filling API
  description: |
    Turn clinician voice input into structured form output. Partners
    create a form-filling session bound to a Suki form template, stream
    audio over the shared WebSocket
    (`wss://sdp.suki-stage.com/api/v1/form-filling/sessions/{sessionId}/audio`),
    end the session, and retrieve the typed structured data to map into
    their own intake, screening, or assessment forms. Webhooks notify
    partner endpoints when structured output is ready.
  version: '1.0.0'
  contact:
    name: Suki for Partners
    url: https://developer.suki.ai
servers:
  - url: https://sdp.suki-stage.com/api/v1
    description: Suki Speech Service staging environment
tags:
  - name: Sessions
    description: Form Filling Session Lifecycle
  - name: Content
    description: Structured Form Output
  - name: Feedback
    description: Field Level Feedback
  - name: Templates
    description: Suki Hosted Form Templates
security:
  - SdpSukiToken: []
paths:
  /form-filling/sessions:
    post:
      tags: [Sessions]
      summary: Create Form Filling Session
      operationId: createFormFillingSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormFillingSessionCreate'
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFillingSession'
  /form-filling/sessions/{sessionId}/context:
    post:
      tags: [Sessions]
      summary: Seed Form Filling Context
      operationId: seedFormFillingContext
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormFillingContext'
      responses:
        '200':
          description: Context applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFillingContext'
    patch:
      tags: [Sessions]
      summary: Update Form Filling Context
      operationId: updateFormFillingContext
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormFillingContext'
      responses:
        '200':
          description: Context updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFillingContext'
  /form-filling/sessions/{sessionId}/end:
    post:
      tags: [Sessions]
      summary: End Form Filling Session
      operationId: endFormFillingSession
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session ended; structured data queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFillingSession'
  /form-filling/sessions/{sessionId}/status:
    get:
      tags: [Sessions]
      summary: Get Form Filling Status
      operationId: getFormFillingStatus
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Processing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormFillingStatus'
  /form-filling/sessions/{sessionId}/structured-data:
    get:
      tags: [Content]
      summary: Get Form Structured Data
      operationId: getFormFillingStructuredData
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Typed structured data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormStructuredData'
  /form-filling/sessions/{sessionId}/feedback:
    post:
      tags: [Feedback]
      summary: Submit Form Filling Feedback
      operationId: submitFormFillingFeedback
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormFillingFeedback'
      responses:
        '202':
          description: Feedback accepted
  /form-filling/templates:
    get:
      tags: [Templates]
      summary: List Form Templates
      operationId: listFormTemplates
      responses:
        '200':
          description: Suki hosted form templates available to the partner
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormTemplate'
components:
  securitySchemes:
    SdpSukiToken:
      type: apiKey
      in: header
      name: sdp_suki_token
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      schema: { type: string, format: uuid }
  schemas:
    FormFillingSessionCreate:
      type: object
      required: [providerId, templateId]
      properties:
        providerId: { type: string }
        templateId: { type: string }
        languageCode: { type: string, example: en-US }
    FormFillingSession:
      type: object
      properties:
        sessionId: { type: string, format: uuid }
        templateId: { type: string }
        status: { type: string, enum: [created, recording, ended, processing, complete] }
        audioWebsocketUrl: { type: string, format: uri }
        createdAt: { type: string, format: date-time }
    FormFillingContext:
      type: object
      properties:
        patient:
          type: object
          properties:
            mrn: { type: string }
            sex: { type: string }
            birthDate: { type: string, format: date }
        priorAnswers:
          type: object
          additionalProperties: true
    FormFillingStatus:
      type: object
      properties:
        sessionId: { type: string, format: uuid }
        status: { type: string }
        progress: { type: integer, minimum: 0, maximum: 100 }
    FormStructuredData:
      type: object
      properties:
        sessionId: { type: string, format: uuid }
        templateId: { type: string }
        fields:
          type: array
          items:
            type: object
            properties:
              fieldId: { type: string }
              label: { type: string }
              type: { type: string, enum: [string, number, boolean, date, choice, multiselect] }
              value: {}
              confidence: { type: number, format: float, minimum: 0, maximum: 1 }
    FormFillingFeedback:
      type: object
      properties:
        fieldId: { type: string }
        accurate: { type: boolean }
        correctedValue: {}
        comments: { type: string }
    FormTemplate:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string }
        version: { type: string }
        fields:
          type: array
          items:
            type: object
            properties:
              fieldId: { type: string }
              label: { type: string }
              type: { type: string }
              required: { type: boolean }