openapi-v2.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Ambient AI Scribe API v1",
    "version": "2.0.0",
    "description": "Auth (password flow), transcription, and template management endpoints for v2 API."
  },
  "servers": [{ "url": "https://api.sandbox.commure.com/ambient/scribe" }],
  "paths": {
    "/v1/auth/token": {
      "post": {
        "summary": "Obtain JWT (OAuth2 password flow)",
        "description": "Authenticate a user and receive a JWT. Send as application/x-www-form-urlencoded.",
        "tags": ["auth"],
        "security": [],
        "parameters": [
          {
            "name": "auth-server",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["cognito"],
              "default": "cognito"
            },
            "description": "Authentication server type. Must be 'cognito'."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": { 
                    "type": "string", 
                    "description": "User email address" 
                  },
                  "password": { 
                    "type": "string", 
                    "format": "password",
                    "description": "User password"
                  }
                },
                "required": ["username", "password"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": { 
                      "type": "string", 
                      "description": "JWT token" 
                    },
                    "token_type": { 
                      "type": "string", 
                      "enum": ["bearer"],
                      "description": "Token type"
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "Token expiration time in seconds"
                    }
                  },
                  "required": ["token", "token_type", "expires_in"]
                },
                "examples": {
                  "default": {
                    "value": {
                      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
                      "token_type": "bearer",
                      "expires_in": 172800
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_credentials": {
                    "value": {
                      "detail": "Incorrect username or password"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { 
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Password flow",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/auth/token \\\n  -H 'Content-Type: application/x-www-form-urlencoded' \\\n  -H 'auth-server: cognito' \\\n  --data-urlencode 'username={email}' \\\n  --data-urlencode 'password={password}'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch JWT",
            "source": "const form = new URLSearchParams({username: process.env.AMBIENT_USER, password: process.env.AMBIENT_PASS});\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/auth/token', { \n  method:'POST', \n  headers:{\n    'Content-Type':'application/x-www-form-urlencoded',\n    'auth-server': 'cognito'\n  }, \n  body: form \n});\nconst {token, token_type, expires_in} = await res.json();"
          },
          {
            "lang": "Python",
            "label": "Requests JWT",
            "source": "import os, requests\nres = requests.post('https://api.sandbox.commure.com/ambient/scribe/v1/auth/token', \n  headers={'auth-server': 'cognito'},\n  data={\n    'username': os.environ['AMBIENT_USER'],\n    'password': os.environ['AMBIENT_PASS']\n  }\n)\ndata = res.json()\ntoken = data['token']"
          }
        ]
      }
    },
    "/v1/transcribe": {
      "post": {
        "summary": "Submit audio file for transcription",
        "description": "Submit an audio file for asynchronous transcription.",
        "tags": ["transcription"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "audio_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio file to transcribe (max 100MB). Supported formats: MP3, WAV, OGG, AAC, FLAC, WEBM, OPUS, AMR, WMA, M4A."
                  }
                },
                "required": ["audio_file"]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Transcription accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transcription_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The transcription record ID. Use this to check transcription status."
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when transcription was submitted"
                    }
                  },
                  "required": ["transcription_id", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful submission",
                    "value": {
                      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
                      "submitted_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid audio file",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "empty_file": {
                    "summary": "Empty audio file",
                    "value": {
                      "detail": "Audio file is empty"
                    }
                  },
                  "missing_file": {
                    "summary": "No file provided",
                    "value": {
                      "detail": "No audio file provided"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Payload too large - audio file exceeds maximum size",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "file_too_large": {
                    "value": {
                      "detail": "Audio file size exceeds maximum allowed size of 100MB"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create transcription workflow"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Upload audio file",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/transcribe \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -F 'audio_file=@/path/to/audio.mp3'"
          },
          {
            "lang": "JavaScript",
            "label": "Upload with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst audioFile = document.getElementById('audioInput').files[0];\n// Or for Node.js:\n// const audioFile = fs.readFileSync('/path/to/audio.mp3');\n\nconst formData = new FormData();\nformData.append('audio_file', audioFile);\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/transcribe', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`\n  },\n  body: formData\n});\n\nconst {transcription_id, submitted_at} = await res.json();\nconsole.log('Transcription ID:', transcription_id);\nconsole.log('Submitted at:', submitted_at);"
          },
          {
            "lang": "Python",
            "label": "Upload with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\naudio_file_path = '/path/to/audio.mp3'\n\nwith open(audio_file_path, 'rb') as audio_file:\n    files = {'audio_file': audio_file}\n    headers = {'Authorization': f'Bearer {token}'}\n    \n    res = requests.post(\n        'https://api.sandbox.commure.com/ambient/scribe/v1/transcribe',\n        headers=headers,\n        files=files\n    )\n\ndata = res.json()\nprint(f\"Transcription ID: {data['transcription_id']}\")\nprint(f\"Submitted at: {data['submitted_at']}\")"
          }
        ]
      }
    },
    "/v1/transcribe/{transcription_id}": {
      "get": {
        "summary": "Get transcription status and results",
        "description": "Retrieve the status and results of a transcription.",
        "tags": ["transcription"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "transcription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the transcription to retrieve",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "responses": {
          "200": {
            "description": "Transcription status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transcription_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The transcription record ID"
                    },
                    "workflow_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The workflow ID associated with this transcription"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "DETECTED_FILE",
                        "STT_PROCESSING",
                        "STT_COMPLETED",
                        "STT_ERROR",
                        "STT_INCOMPLETE"
                      ],
                      "description": "Current transcription status:\n- `DETECTED_FILE`: File detected and queued for processing\n- `STT_PROCESSING`: Speech-to-text processing in progress\n- `STT_COMPLETED`: Transcription completed successfully\n- `STT_ERROR`: Error occurred during transcription\n- `STT_INCOMPLETE`: Transcription incomplete or partial"
                    },
                    "raw_text": {
                      "type": "string",
                      "nullable": true,
                      "description": "Transcription text if available (null if still processing or error occurred)"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When transcription was created"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When transcription was last updated"
                    }
                  },
                  "required": ["transcription_id", "workflow_id", "status", "created_at", "updated_at"]
                },
                "examples": {
                  "completed": {
                    "summary": "Completed transcription",
                    "value": {
                      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
                      "workflow_id": "123e4567-e89b-12d3-a456-426614174001",
                      "status": "STT_COMPLETED",
                      "raw_text": "Patient presents with chief complaint of persistent cough for the past two weeks. Patient reports the cough is dry and worse at night. No fever, no shortness of breath. Patient denies any recent travel or sick contacts. On examination, lungs are clear to auscultation bilaterally. Vital signs are within normal limits. Assessment: Upper respiratory tract infection. Plan: Recommend over-the-counter cough suppressant, increase fluid intake, and follow up if symptoms worsen or persist beyond one week.",
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:35:00Z"
                    }
                  },
                  "processing": {
                    "summary": "Processing transcription",
                    "value": {
                      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
                      "workflow_id": "123e4567-e89b-12d3-a456-426614174001",
                      "status": "STT_PROCESSING",
                      "raw_text": null,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:31:00Z"
                    }
                  },
                  "detected": {
                    "summary": "File detected (queued)",
                    "value": {
                      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
                      "workflow_id": "123e4567-e89b-12d3-a456-426614174001",
                      "status": "DETECTED_FILE",
                      "raw_text": null,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:30:00Z"
                    }
                  },
                  "error": {
                    "summary": "Transcription error",
                    "value": {
                      "transcription_id": "123e4567-e89b-12d3-a456-426614174000",
                      "workflow_id": "123e4567-e89b-12d3-a456-426614174001",
                      "status": "STT_ERROR",
                      "raw_text": null,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:32:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid transcription ID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid transcription ID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Transcription not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Transcription not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Internal server error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get transcription status",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/transcribe/123e4567-e89b-12d3-a456-426614174000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch transcription status",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst transcriptionId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/transcribe/${transcriptionId}`,\n  {\n    headers: {\n      'Authorization': `Bearer ${token}`\n    }\n  }\n);\n\nconst transcription = await res.json();\nconsole.log('Status:', transcription.status);\nif (transcription.raw_text) {\n  console.log('Transcription:', transcription.raw_text);\n}\n\n// Poll for completion\nwhile (transcription.status === 'STT_PROCESSING' || transcription.status === 'DETECTED_FILE') {\n  await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds\n  const res = await fetch(\n    `https://api.sandbox.commure.com/ambient/scribe/v1/transcribe/${transcriptionId}`,\n    { headers: { 'Authorization': `Bearer ${token}` } }\n  );\n  transcription = await res.json();\n  console.log('Status:', transcription.status);\n}"
          },
          {
            "lang": "Python",
            "label": "Get transcription with polling",
            "source": "import requests\nimport time\n\ntoken = 'YOUR_JWT_TOKEN'\ntranscription_id = '123e4567-e89b-12d3-a456-426614174000'\n\ndef get_transcription_status(transcription_id, token):\n    res = requests.get(\n        f'https://api.sandbox.commure.com/ambient/scribe/v1/transcribe/{transcription_id}',\n        headers={'Authorization': f'Bearer {token}'}\n    )\n    return res.json()\n\n# Get initial status\ntranscription = get_transcription_status(transcription_id, token)\nprint(f\"Status: {transcription['status']}\")\n\n# Poll until completed or error\nwhile transcription['status'] in ['DETECTED_FILE', 'STT_PROCESSING']:\n    print(f\"Status: {transcription['status']} - waiting...\")\n    time.sleep(5)  # Wait 5 seconds\n    transcription = get_transcription_status(transcription_id, token)\n\nif transcription['status'] == 'STT_COMPLETED':\n    print(f\"Transcription completed!\")\n    print(f\"Text: {transcription['raw_text']}\")\nelse:\n    print(f\"Transcription failed with status: {transcription['status']}\")"
          }
        ]
      }
    },
    "/v1/templates": {
      "post": {
        "summary": "Create a new template",
        "description": "Create a new template with a JSON Schema definition. Templates define the structure for generating clinical notes from transcriptions.",
        "tags": ["templates"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "template_name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Name of the template",
                    "example": "Primary Care Visit Note"
                  },
                  "template_description": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Description of the template",
                    "example": "Template for documenting primary care visits including chief complaint, history, exam, and plan"
                  },
                  "template_content": {
                    "description": "JSON Schema object defining your template structure."
                  }
                  }
              },
              "examples": {
                "soap_note": {
                  "summary": "SOAP Note Template",
                  "value": {
                    "template_name": "SOAP Note",
                    "template_description": "Standard SOAP format for clinical documentation",
                    "template_content": {
                      "type": "object",
                      "required": ["subjective", "objective", "assessment", "plan"],
                      "properties": {
                        "subjective": {
                          "type": "string",
                          "title": "Subjective",
                          "description": "Patient's chief complaint and history of present illness"
                        },
                        "objective": {
                          "type": "string",
                          "title": "Objective",
                          "description": "Physical examination findings and vital signs"
                        },
                        "assessment": {
                          "type": "string",
                          "title": "Assessment",
                          "description": "Clinical assessment and diagnosis"
                        },
                        "plan": {
                          "type": "string",
                          "title": "Plan",
                          "description": "Treatment plan and follow-up instructions"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_uuid": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Universally unique identifier (UUID) for the created template"
                    }
                  },
                  "required": ["template_uuid"]
                },
                "examples": {
                  "success": {
                    "value": {
                      "template_uuid": "550e8400-e29b-41d4-a716-446655440000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid template content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "empty_content": {
                    "value": {
                      "detail": "Template content is empty, unable to create template"
                    }
                  },
                  "validation_error": {
                    "value": {
                      "detail": "template_content type must be 'object'"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create template"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Create SOAP template",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/templates \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"template_name\": \"SOAP Note\",\n    \"template_description\": \"Standard SOAP format\",\n    \"template_content\": {\n      \"type\": \"object\",\n      \"required\": [\"subjective\", \"objective\", \"assessment\", \"plan\"],\n      \"properties\": {\n        \"subjective\": {\"type\": \"string\", \"title\": \"Subjective\"},\n        \"objective\": {\"type\": \"string\", \"title\": \"Objective\"},\n        \"assessment\": {\"type\": \"string\", \"title\": \"Assessment\"},\n        \"plan\": {\"type\": \"string\", \"title\": \"Plan\"}\n      }\n    }\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Create template with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst template = {\n  template_name: 'SOAP Note',\n  template_description: 'Standard SOAP format',\n  template_content: {\n    type: 'object',\n    required: ['subjective', 'objective', 'assessment', 'plan'],\n    properties: {\n      subjective: {type: 'string', title: 'Subjective'},\n      objective: {type: 'string', title: 'Objective'},\n      assessment: {type: 'string', title: 'Assessment'},\n      plan: {type: 'string', title: 'Plan'}\n    }\n  }\n};\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/templates', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(template)\n});\n\nconst {template_uuid} = await res.json();\nconsole.log('Created template:', template_uuid);"
          },
          {
            "lang": "Python",
            "label": "Create template with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate = {\n    'template_name': 'SOAP Note',\n    'template_description': 'Standard SOAP format',\n    'template_content': {\n        'type': 'object',\n        'required': ['subjective', 'objective', 'assessment', 'plan'],\n        'properties': {\n            'subjective': {'type': 'string', 'title': 'Subjective'},\n            'objective': {'type': 'string', 'title': 'Objective'},\n            'assessment': {'type': 'string', 'title': 'Assessment'},\n            'plan': {'type': 'string', 'title': 'Plan'}\n        }\n    }\n}\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/templates',\n    headers={'Authorization': f'Bearer {token}'},\n    json=template\n)\n\ndata = res.json()\nprint(f\"Created template: {data['template_uuid']}\")"
          }
        ]
      },
      "get": {
        "summary": "List all templates",
        "description": "Retrieve a list of all templates belonging to the authenticated user's scribe account.",
        "tags": ["templates"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "responses": {
          "200": {
            "description": "Templates retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "template_uuid": {
                            "type": "string",
                            "format": "uuid",
                            "description": "Universally unique identifier (UUID) for the template"
                          },
                          "template_name": {
                            "type": "string",
                            "description": "Name of the template"
                          },
                          "template_description": {
                            "type": "string",
                            "description": "Description of the template"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Timestamp when the template was created"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Timestamp when the template was last updated"
                          },
                          "active": {
                            "type": "boolean",
                            "description": "Whether the template is active"
                          }
                        },
                        "required": ["template_uuid", "created_at", "updated_at", "active"]
                      }
                    }
                  },
                  "required": ["templates"]
                },
                "examples": {
                  "success": {
                    "value": {
                      "templates": [
                        {
                          "template_uuid": "550e8400-e29b-41d4-a716-446655440000",
                          "template_name": "SOAP Note",
                          "template_description": "Standard SOAP format for clinical documentation",
                          "created_at": "2025-01-02T10:30:00Z",
                          "updated_at": "2025-01-02T10:30:00Z",
                          "active": true
                        },
                        {
                          "template_uuid": "550e8400-e29b-41d4-a716-446655440001",
                          "template_name": "Progress Note",
                          "template_description": "Template for progress notes",
                          "created_at": "2025-01-01T08:00:00Z",
                          "updated_at": "2025-01-01T08:00:00Z",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to list templates"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "List templates",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/templates \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch templates",
            "source": "const token = 'YOUR_JWT_TOKEN';\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/templates', {\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito'\n  }\n});\n\nconst {templates} = await res.json();\nconsole.log(`Found ${templates.length} templates`);\ntemplates.forEach(t => {\n  console.log(`${t.template_name} (${t.template_uuid}) - Active: ${t.active}`);\n});"
          },
          {
            "lang": "Python",
            "label": "List templates with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\n\nres = requests.get(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/templates',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'auth-scheme': 'cognito'\n    }\n)\n\ndata = res.json()\nprint(f\"Found {len(data['templates'])} templates\")\nfor template in data['templates']:\n    print(f\"{template['template_name']} ({template['template_uuid']}) - Active: {template['active']}\")"
          }
        ]
      }
    },
    "/v1/templates/{template_id}": {
      "get": {
        "summary": "Get a template by ID",
        "description": "Retrieve a template's details including its content schema, name, description, and timestamps.",
        "tags": ["templates"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the template to retrieve",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "responses": {
          "200": {
            "description": "Template retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_uuid": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Universally unique identifier (UUID) for the template"
                    },
                    "template_name": {
                      "type": "string",
                      "description": "Name of the template"
                    },
                    "template_content": {
                      "type": "object",
                      "description": "JSON Schema defining the template structure",
                      "additionalProperties": true
                    },
                    "template_description": {
                      "type": "string",
                      "description": "Description of the template"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the template was created"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the template was last updated"
                    }
                  },
                  "required": ["template_uuid", "template_content", "created_at", "updated_at"]
                },
                "examples": {
                  "soap_note": {
                    "summary": "SOAP Note Template",
                    "value": {
                      "template_uuid": "550e8400-e29b-41d4-a716-446655440000",
                      "template_name": "SOAP Note",
                      "template_description": "Standard SOAP format for clinical documentation",
                      "template_content": {
                        "type": "object",
                        "required": ["subjective", "objective", "assessment", "plan"],
                        "properties": {
                          "subjective": {
                            "type": "string",
                            "title": "Subjective",
                            "description": "Patient's chief complaint and history of present illness"
                          },
                          "objective": {
                            "type": "string",
                            "title": "Objective",
                            "description": "Physical examination findings and vital signs"
                          },
                          "assessment": {
                            "type": "string",
                            "title": "Assessment",
                            "description": "Clinical assessment and diagnosis"
                          },
                          "plan": {
                            "type": "string",
                            "title": "Plan",
                            "description": "Treatment plan and follow-up instructions"
                          }
                        }
                      },
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid template ID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid UUID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Template with id 550e8400-e29b-41d4-a716-446655440000 not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Internal server error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get template",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/templates/550e8400-e29b-41d4-a716-446655440000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch template",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst templateId = '550e8400-e29b-41d4-a716-446655440000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/templates/${templateId}`,\n  {\n    headers: {\n      'Authorization': `Bearer ${token}`\n    }\n  }\n);\n\nconst template = await res.json();\nconsole.log('Template:', template.template_name);\nconsole.log('Content:', template.template_content);"
          },
          {
            "lang": "Python",
            "label": "Get template with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '550e8400-e29b-41d4-a716-446655440000'\n\nres = requests.get(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/templates/{template_id}',\n    headers={'Authorization': f'Bearer {token}'}\n)\n\ntemplate = res.json()\nprint(f\"Template: {template['template_name']}\")\nprint(f\"Created: {template['created_at']}\")"
          }
        ]
      },
      "put": {
        "summary": "Update an existing template",
        "description": "Update a template's name, content, and description. The template content will be replaced entirely with the new content.",
        "tags": ["templates"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the template to update",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "template_name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Name of the template",
                    "example": "Primary Care Visit Note"
                  },
                  "template_description": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Description of the template",
                    "example": "Template for documenting primary care visits including chief complaint, history, exam, and plan"
                  },
                  "template_content": {
                    "description": "JSON Schema object defining your template structure."
                  }
                  }
              },
              "examples": {
                "soap_note": {
                  "summary": "Update SOAP Note Template",
                  "value": {
                    "template_name": "SOAP Note",
                    "template_description": "Standard SOAP format for clinical documentation",
                    "template_content": {
                      "type": "object",
                      "required": ["subjective", "objective", "assessment", "plan"],
                      "properties": {
                        "subjective": {
                          "type": "string",
                          "title": "Subjective",
                          "description": "Patient's chief complaint and history of present illness"
                        },
                        "objective": {
                          "type": "string",
                          "title": "Objective",
                          "description": "Physical examination findings and vital signs"
                        },
                        "assessment": {
                          "type": "string",
                          "title": "Assessment",
                          "description": "Clinical assessment and diagnosis"
                        },
                        "plan": {
                          "type": "string",
                          "title": "Plan",
                          "description": "Treatment plan and follow-up instructions"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_uuid": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Universally unique identifier (UUID) for the updated template"
                    }
                  },
                  "required": ["template_uuid"]
                },
                "examples": {
                  "success": {
                    "value": {
                      "template_uuid": "550e8400-e29b-41d4-a716-446655440000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid template content or structure",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "empty_content": {
                    "value": {
                      "detail": "Template content is empty, unable to update template"
                    }
                  },
                  "validation_error": {
                    "value": {
                      "detail": "template_content type must be 'object'"
                    }
                  },
                  "invalid_structure": {
                    "value": {
                      "detail": "Template structure is not valid. Errors: properties cannot be empty"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Template with id 550e8400-e29b-41d4-a716-446655440000 not found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to update template"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Update SOAP template",
            "source": "curl -X PUT https://api.sandbox.commure.com/ambient/scribe/v1/templates/550e8400-e29b-41d4-a716-446655440000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"template_name\": \"SOAP Note\",\n    \"template_description\": \"Standard SOAP format\",\n    \"template_content\": {\n      \"type\": \"object\",\n      \"required\": [\"subjective\", \"objective\", \"assessment\", \"plan\"],\n      \"properties\": {\n        \"subjective\": {\"type\": \"string\", \"title\": \"Subjective\"},\n        \"objective\": {\"type\": \"string\", \"title\": \"Objective\"},\n        \"assessment\": {\"type\": \"string\", \"title\": \"Assessment\"},\n        \"plan\": {\"type\": \"string\", \"title\": \"Plan\"}\n      }\n    }\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Update template with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst templateId = '550e8400-e29b-41d4-a716-446655440000';\nconst template = {\n  template_name: 'SOAP Note',\n  template_description: 'Standard SOAP format',\n  template_content: {\n    type: 'object',\n    required: ['subjective', 'objective', 'assessment', 'plan'],\n    properties: {\n      subjective: {type: 'string', title: 'Subjective'},\n      objective: {type: 'string', title: 'Objective'},\n      assessment: {type: 'string', title: 'Assessment'},\n      plan: {type: 'string', title: 'Plan'}\n    }\n  }\n};\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/templates/${templateId}`,\n  {\n    method: 'PUT',\n    headers: {\n      'Authorization': `Bearer ${token}`,\n      'Content-Type': 'application/json'\n    },\n    body: JSON.stringify(template)\n  }\n);\n\nconst {template_uuid} = await res.json();\nconsole.log('Updated template:', template_uuid);"
          },
          {
            "lang": "Python",
            "label": "Update template with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '550e8400-e29b-41d4-a716-446655440000'\ntemplate = {\n    'template_name': 'SOAP Note',\n    'template_description': 'Standard SOAP format',\n    'template_content': {\n        'type': 'object',\n        'required': ['subjective', 'objective', 'assessment', 'plan'],\n        'properties': {\n            'subjective': {'type': 'string', 'title': 'Subjective'},\n            'objective': {'type': 'string', 'title': 'Objective'},\n            'assessment': {'type': 'string', 'title': 'Assessment'},\n            'plan': {'type': 'string', 'title': 'Plan'}\n        }\n    }\n}\n\nres = requests.put(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/templates/{template_id}',\n    headers={'Authorization': f'Bearer {token}'},\n    json=template\n)\n\ndata = res.json()\nprint(f\"Updated template: {data['template_uuid']}\")"
          }
        ]
      },
      "delete": {
        "summary": "Delete a template",
        "description": "Mark a template as inactive (soft delete).",
        "tags": ["templates"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the template to delete",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "responses": {
          "200": {
            "description": "Template deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template_uuid": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Universally unique identifier (UUID) for the deleted template"
                    },
                    "message": {
                      "type": "string",
                      "description": "Confirmation message",
                      "example": "Template deleted successfully"
                    }
                  },
                  "required": ["template_uuid", "message"]
                },
                "examples": {
                  "success": {
                    "value": {
                      "template_uuid": "550e8400-e29b-41d4-a716-446655440000",
                      "message": "Template deleted successfully"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid template ID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid UUID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Template with id 550e8400-e29b-41d4-a716-446655440000 not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to delete template"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Delete template",
            "source": "curl -X DELETE https://api.sandbox.commure.com/ambient/scribe/v1/templates/550e8400-e29b-41d4-a716-446655440000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Delete template with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst templateId = '550e8400-e29b-41d4-a716-446655440000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/templates/${templateId}`,\n  {\n    method: 'DELETE',\n    headers: {\n      'Authorization': `Bearer ${token}`,\n      'auth-scheme': 'cognito'\n    }\n  }\n);\n\nconst {template_uuid, message} = await res.json();\nconsole.log(message);"
          },
          {
            "lang": "Python",
            "label": "Delete template with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '550e8400-e29b-41d4-a716-446655440000'\n\nres = requests.delete(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/templates/{template_id}',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'auth-scheme': 'cognito'\n    }\n)\n\ndata = res.json()\nprint(f\"{data['message']}\")\nprint(f\"Deleted template: {data['template_uuid']}\")"
          }
        ]
      }
    },
    "/v1/scribe": {
      "post": {
        "summary": "Submit scribe workflow for note generation",
        "description": "Submit a scribe workflow with either an audio file or pre-existing transcript for clinical note generation.",
        "tags": ["scribe"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["template_id", "date_of_service"],
                "properties": {
                  "template_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Template ID for note generation",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                  },
                  "date_of_service": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Date of service in ISO format (e.g., '2025-01-02T10:30:00Z')",
                    "example": "2025-01-02T10:30:00Z"
                  },
                  "audio_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio file to transcribe (mutually exclusive with transcript). Supported formats: MP3, WAV, OGG, AAC, FLAC, WEBM, OPUS, AMR, WMA, M4A. Max size: 100MB."
                  },
                  "transcript": {
                    "type": "string",
                    "minLength": 10,
                    "description": "Pre-existing transcript text (mutually exclusive with audio_file). If provided, note generation will start immediately without transcription. Must contain at least 10 words (minimum requirement for note generation).",
                    "example": "Patient presents with chief complaint of persistent cough for the past two weeks. Reports difficulty breathing and occasional chest tightness."
                  },
                  "patient_name": {
                    "type": "string",
                    "description": "Optional patient name",
                    "example": "John Doe"
                  },
                  "gender": {
                    "type": "string",
                    "enum": ["MALE", "FEMALE", "OTHER", "UNKNOWN"],
                    "description": "Optional patient gender",
                    "example": "MALE"
                  },
                  "birth_date": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Optional patient birth date in ISO format (e.g., '1980-05-15T00:00:00Z')",
                    "example": "1980-05-15T00:00:00Z"
                  },
                  "appointment_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional appointment ID",
                    "example": "123e4567-e89b-12d3-a456-426614174000"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Scribe workflow accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scribe_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique scribe identifier. Use this to check workflow status and retrieve generated notes."
                    },
                    "status": {
                      "type": "string",
                      "description": "Current workflow status",
                      "example": "IN_PROGRESS"
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the workflow was submitted"
                    }
                  },
                  "required": ["scribe_id", "status", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful submission",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "IN_PROGRESS",
                      "submitted_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "missing_input": {
                    "value": {
                      "detail": "Either audio_file or transcript must be provided"
                    }
                  },
                  "both_provided": {
                    "value": {
                      "detail": "Only one of audio_file or transcript can be provided, not both"
                    }
                  },
                  "invalid_date": {
                    "value": {
                      "detail": "Invalid date_of_service format: invalid isoformat string"
                    }
                  },
                  "invalid_birth_date": {
                    "value": {
                      "detail": "Invalid birth_date format: invalid isoformat string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "template_not_found": {
                    "value": {
                      "detail": "Template with id 550e8400-e29b-41d4-a716-446655440000 not found"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Payload too large - audio file exceeds maximum size",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "file_too_large": {
                    "value": {
                      "detail": "Audio file size exceeds maximum allowed size of 100MB"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "upload_failed": {
                    "value": {
                      "detail": "Failed to upload audio file to GCS: [error details]"
                    }
                  },
                  "server_error": {
                    "value": {
                      "detail": "Failed to create scribe workflow"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Submit with audio file",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/scribe \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -F 'template_id=550e8400-e29b-41d4-a716-446655440000' \\\n  -F 'date_of_service=2025-01-02T10:30:00Z' \\\n  -F 'audio_file=@/path/to/audio.mp3' \\\n  -F 'patient_name=John Doe' \\\n  -F 'gender=MALE' \\\n  -F 'birth_date=1980-05-15T00:00:00Z'"
          },
          {
            "lang": "cURL",
            "label": "Submit with transcript",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/scribe \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -F 'template_id=550e8400-e29b-41d4-a716-446655440000' \\\n  -F 'date_of_service=2025-01-02T10:30:00Z' \\\n  -F 'transcript=Patient presents with chief complaint of persistent cough for the past two weeks...' \\\n  -F 'patient_name=John Doe'"
          },
          {
            "lang": "JavaScript",
            "label": "Submit with audio file",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst audioFile = document.getElementById('audioInput').files[0];\n// Or for Node.js:\n// const audioFile = fs.readFileSync('/path/to/audio.mp3');\n\nconst formData = new FormData();\nformData.append('template_id', '550e8400-e29b-41d4-a716-446655440000');\nformData.append('date_of_service', '2025-01-02T10:30:00Z');\nformData.append('audio_file', audioFile);\nformData.append('patient_name', 'John Doe');\nformData.append('gender', 'MALE');\nformData.append('birth_date', '1980-05-15T00:00:00Z');\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/scribe', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`\n  },\n  body: formData\n});\n\nconst {scribe_id, status, submitted_at} = await res.json();\nconsole.log('Scribe ID:', scribe_id);\nconsole.log('Status:', status);"
          },
          {
            "lang": "JavaScript",
            "label": "Submit with transcript",
            "source": "const token = 'YOUR_JWT_TOKEN';\n\nconst formData = new FormData();\nformData.append('template_id', '550e8400-e29b-41d4-a716-446655440000');\nformData.append('date_of_service', '2025-01-02T10:30:00Z');\nformData.append('transcript', 'Patient presents with chief complaint of persistent cough for the past two weeks. Patient reports the cough is dry and worse at night...');\nformData.append('patient_name', 'John Doe');\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/scribe', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`\n  },\n  body: formData\n});\n\nconst {scribe_id, status, submitted_at} = await res.json();\nconsole.log('Scribe ID:', scribe_id);"
          },
          {
            "lang": "Python",
            "label": "Submit with audio file",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '550e8400-e29b-41d4-a716-446655440000'\naudio_file_path = '/path/to/audio.mp3'\n\nwith open(audio_file_path, 'rb') as audio_file:\n    files = {'audio_file': audio_file}\n    data = {\n        'template_id': template_id,\n        'date_of_service': '2025-01-02T10:30:00Z',\n        'patient_name': 'John Doe',\n        'gender': 'MALE',\n        'birth_date': '1980-05-15T00:00:00Z'\n    }\n    headers = {'Authorization': f'Bearer {token}'}\n    \n    res = requests.post(\n        'https://api.sandbox.commure.com/ambient/scribe/v1/scribe',\n        headers=headers,\n        files=files,\n        data=data\n    )\n\ndata = res.json()\nprint(f\"Scribe ID: {data['scribe_id']}\")\nprint(f\"Status: {data['status']}\")"
          },
          {
            "lang": "Python",
            "label": "Submit with transcript",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '550e8400-e29b-41d4-a716-446655440000'\ntranscript = 'Patient presents with chief complaint of persistent cough for the past two weeks. Patient reports the cough is dry and worse at night...'\n\ndata = {\n    'template_id': template_id,\n    'date_of_service': '2025-01-02T10:30:00Z',\n    'transcript': transcript,\n    'patient_name': 'John Doe'\n}\nheaders = {'Authorization': f'Bearer {token}'}\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/scribe',\n    headers=headers,\n    data=data\n)\n\ndata = res.json()\nprint(f\"Scribe ID: {data['scribe_id']}\")\nprint(f\"Status: {data['status']}\")"
          }
        ]
      }
    },
    "/v1/scribe/{scribe_id}": {
      "get": {
        "summary": "Get scribe details and generated notes",
        "description": "Retrieve scribe workflow details including status, generated clinical notes, and metadata.",
        "tags": ["scribe"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "scribe_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the scribe workflow to retrieve",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "responses": {
          "200": {
            "description": "Scribe details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scribe_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique scribe identifier"
                    },
                    "status": {
                      "type": "string",
                      "description": "Current workflow status",
                      "example": "COMPLETED"
                    },
                    "date_of_service": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Date of service"
                    },
                    "audio_length_in_seconds": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Audio duration in seconds (if audio file was provided)"
                    },
                    "additional_context": {
                      "type": "object",
                      "nullable": true,
                      "description": "Additional context metadata",
                      "additionalProperties": true
                    },
                    "ai_tasks": {
                      "type": "array",
                      "description": "Generated clinical notes",
                      "items": {
                        "type": "object",
                        "properties": {
                          "template_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "Template ID used for note generation"
                          },
                          "note_json": {
                            "type": "object",
                            "nullable": true,
                            "description": "Structured note output in JSON format matching the template schema",
                            "additionalProperties": true
                          },
                          "note_text": {
                            "type": "string",
                            "nullable": true,
                            "description": "Plain text note output"
                          }
                        }
                      }
                    },
                    "error_message": {
                      "type": "string",
                      "nullable": true,
                      "description": "Error message if workflow failed"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the scribe workflow was created"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the scribe workflow was last updated"
                    }
                  },
                  "required": ["scribe_id", "status", "date_of_service", "ai_tasks", "created_at", "updated_at"]
                },
                "examples": {
                  "completed": {
                    "summary": "Completed workflow with notes",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "COMPLETED",
                      "date_of_service": "2025-01-02T10:30:00Z",
                      "audio_length_in_seconds": 300,
                      "additional_context": {
                        "patient_name": "John Doe",
                        "gender": "MALE"
                      },
                      "ai_tasks": [
                        {
                          "template_id": "550e8400-e29b-41d4-a716-446655440000",
                          "note_json": {
                            "subjective": "Patient presents with chief complaint of persistent cough for the past two weeks.",
                            "objective": "Lungs are clear to auscultation bilaterally. Vital signs are within normal limits.",
                            "assessment": "Upper respiratory tract infection",
                            "plan": "Recommend over-the-counter cough suppressant, increase fluid intake, and follow up if symptoms worsen."
                          },
                          "note_text": "SUBJECTIVE: Patient presents with chief complaint of persistent cough for the past two weeks.\n\nOBJECTIVE: Lungs are clear to auscultation bilaterally. Vital signs are within normal limits.\n\nASSESSMENT: Upper respiratory tract infection\n\nPLAN: Recommend over-the-counter cough suppressant, increase fluid intake, and follow up if symptoms worsen."
                        }
                      ],
                      "error_message": null,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:35:00Z"
                    }
                  },
                  "in_progress": {
                    "summary": "Workflow in progress",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "IN_PROGRESS",
                      "date_of_service": "2025-01-02T10:30:00Z",
                      "audio_length_in_seconds": 300,
                      "additional_context": null,
                      "ai_tasks": [],
                      "error_message": null,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:31:00Z"
                    }
                  },
                  "failed": {
                    "summary": "Failed workflow",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "FAILED",
                      "date_of_service": "2025-01-02T10:30:00Z",
                      "audio_length_in_seconds": null,
                      "additional_context": null,
                      "ai_tasks": [],
                      "error_message": "Transcription failed: Unable to process audio file",
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:32:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid scribe ID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid UUID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - scribe does not belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "access_denied": {
                    "value": {
                      "detail": "Access denied to this scribe"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Scribe not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Scribe not found: [error details]"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Internal server error"
                    }
                  },
                  "missing_dependencies": {
                    "value": {
                      "detail": "Missing required dependencies"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get scribe details",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/scribe/123e4567-e89b-12d3-a456-426614174000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch scribe details",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst scribeId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/scribe/${scribeId}`,\n  {\n    headers: {\n      'Authorization': `Bearer ${token}`\n    }\n  }\n);\n\nconst scribe = await res.json();\nconsole.log('Status:', scribe.status);\nconsole.log('AI Tasks:', scribe.ai_tasks);\n\nif (scribe.status === 'COMPLETED' && scribe.ai_tasks.length > 0) {\n  console.log('Generated note:', scribe.ai_tasks[0].note_text);\n  console.log('Structured note:', scribe.ai_tasks[0].note_json);\n} else if (scribe.status === 'IN_PROGRESS') {\n  console.log('Workflow is still processing...');\n} else if (scribe.status === 'FAILED') {\n  console.error('Workflow failed:', scribe.error_message);\n}"
          },
          {
            "lang": "Python",
            "label": "Get scribe with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\nscribe_id = '123e4567-e89b-12d3-a456-426614174000'\n\nres = requests.get(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/scribe/{scribe_id}',\n    headers={'Authorization': f'Bearer {token}'}\n)\n\nscribe = res.json()\nprint(f\"Status: {scribe['status']}\")\nprint(f\"Date of Service: {scribe['date_of_service']}\")\n\nif scribe['status'] == 'COMPLETED' and scribe['ai_tasks']:\n    note = scribe['ai_tasks'][0]\n    print(f\"\\nGenerated Note Text:\\n{note['note_text']}\")\n    print(f\"\\nStructured Note JSON:\\n{note['note_json']}\")\nelif scribe['status'] == 'IN_PROGRESS':\n    print(\"Workflow is still processing...\")\nelif scribe['status'] == 'FAILED':\n    print(f\"Workflow failed: {scribe['error_message']}\")"
          },
          {
            "lang": "Python",
            "label": "Poll for completion",
            "source": "import requests\nimport time\n\ntoken = 'YOUR_JWT_TOKEN'\nscribe_id = '123e4567-e89b-12d3-a456-426614174000'\n\ndef get_scribe_status(scribe_id, token):\n    res = requests.get(\n        f'https://api.sandbox.commure.com/ambient/scribe/v1/scribe/{scribe_id}',\n        headers={'Authorization': f'Bearer {token}'}\n    )\n    return res.json()\n\n# Get initial status\nscribe = get_scribe_status(scribe_id, token)\nprint(f\"Status: {scribe['status']}\")\n\n# Poll until completed or failed\nwhile scribe['status'] in ['IN_PROGRESS', 'PENDING']:\n    print(f\"Status: {scribe['status']} - waiting...\")\n    time.sleep(5)  # Wait 5 seconds\n    scribe = get_scribe_status(scribe_id, token)\n\nif scribe['status'] == 'COMPLETED':\n    print(\"\\nWorkflow completed!\")\n    for note in scribe['ai_tasks']:\n        print(f\"\\nNote from template {note['template_id']}:\")\n        print(note['note_text'])\nelse:\n    print(f\"\\nWorkflow failed: {scribe['error_message']}\")"
          }
        ]
      }
    },
    "/v1/scribe/{scribe_id}/regenerate/text": {
      "post": {
        "summary": "Regenerate scribe with additional transcript",
        "description": "Regenerate a scribe using existing transcriptions and adding user context.",
        "tags": ["regenerate"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "scribe_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the scribe workflow to regenerate",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["transcript"],
                "properties": {
                  "transcript": {
                    "type": "string",
                    "description": "Additional transcript or modification instructions for regenerating the notes",
                    "example": "Please add more details about the patient's symptoms and include medication dosages"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Regeneration request accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scribe_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique scribe identifier"
                    },
                    "status": {
                      "type": "string",
                      "description": "Current workflow status (REGENERATING)",
                      "example": "REGENERATING"
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the regeneration request was submitted"
                    }
                  },
                  "required": ["scribe_id", "status", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful regeneration request",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "REGENERATING",
                      "submitted_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "empty_context": {
                    "value": {
                      "detail": "transcript is required and cannot be empty"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Scribe not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Scribe with id 123e4567-e89b-12d3-a456-426614174000 not found"
                    }
                  },
                  "access_denied": {
                    "value": {
                      "detail": "Scribe 123e4567-e89b-12d3-a456-426614174000 does not belong to account"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to regenerate scribe: [error details]"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Regenerate with text context",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/scribe/123e4567-e89b-12d3-a456-426614174000/regenerate/text \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -F 'transcript=Please add more details about the patient\\'s symptoms'"
          },
          {
            "lang": "JavaScript",
            "label": "Regenerate with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst scribeId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst formData = new FormData();\nformData.append('transcript', 'Please add more details about the patient\\'s symptoms');\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/scribe/${scribeId}/regenerate/text`,\n  {\n    method: 'POST',\n    headers: {\n      'Authorization': `Bearer ${token}`\n    },\n    body: formData\n  }\n);\n\nconst {scribe_id, status, submitted_at} = await res.json();\nconsole.log('Regeneration started:', scribe_id);"
          },
          {
            "lang": "Python",
            "label": "Regenerate with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\nscribe_id = '123e4567-e89b-12d3-a456-426614174000'\n\ndata = {\n    'transcript': 'Please add more details about the patient\\'s symptoms'\n}\n\nres = requests.post(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/scribe/{scribe_id}/regenerate/text',\n    headers={'Authorization': f'Bearer {token}'},\n    data=data\n)\n\nresult = res.json()\nprint(f\"Regeneration started: {result['scribe_id']}\")\nprint(f\"Status: {result['status']}\")"
          }
        ]
      }
    },
    "/v1/scribe/{scribe_id}/regenerate/audio": {
      "post": {
        "summary": "Regenerate scribe workflow with new audio files",
        "description": "Regenerate a scribe workflow by uploading new audio files for transcription.",
        "tags": ["regenerate"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "scribe_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the scribe workflow to regenerate",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["audio_file"],
                "properties": {
                  "audio_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Audio file to transcribe. Supported formats: MP3, WAV, OGG, AAC, FLAC, WEBM, OPUS, AMR, WMA, M4A. Max size: 100MB."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Regeneration request accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scribe_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique scribe identifier"
                    },
                    "status": {
                      "type": "string",
                      "description": "Current workflow status (REGENERATING)",
                      "example": "REGENERATING"
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when the regeneration request was submitted"
                    }
                  },
                  "required": ["scribe_id", "status", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful regeneration request",
                    "value": {
                      "scribe_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "REGENERATING",
                      "submitted_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "no_files": {
                    "value": {
                      "detail": "audio_file is required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Scribe not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Scribe with id 123e4567-e89b-12d3-a456-426614174000 not found"
                    }
                  },
                  "access_denied": {
                    "value": {
                      "detail": "Scribe 123e4567-e89b-12d3-a456-426614174000 does not belong to account"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Payload too large - audio file exceeds maximum size",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "file_too_large": {
                    "value": {
                      "detail": "Audio file size exceeds maximum allowed size of 100MB"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to regenerate scribe: [error details]"
                    }
                  },
                  "upload_failed": {
                    "value": {
                      "detail": "Failed to upload audio file to GCS: [error details]"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Regenerate with audio file",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/scribe/123e4567-e89b-12d3-a456-426614174000/regenerate/audio \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -F 'audio_file=@/path/to/audio.mp3'"
          },
          {
            "lang": "JavaScript",
            "label": "Regenerate with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst scribeId = '123e4567-e89b-12d3-a456-426614174000';\nconst audioFile = document.getElementById('audioInput').files[0];\n// Or for Node.js:\n// const audioFile = fs.readFileSync('/path/to/audio.mp3');\n\nconst formData = new FormData();\nformData.append('audio_file', audioFile);\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/scribe/${scribeId}/regenerate/audio`,\n  {\n    method: 'POST',\n    headers: {\n      'Authorization': `Bearer ${token}`\n    },\n    body: formData\n  }\n);\n\nconst {scribe_id, status, submitted_at} = await res.json();\nconsole.log('Regeneration started:', scribe_id);"
          },
          {
            "lang": "Python",
            "label": "Regenerate with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\nscribe_id = '123e4567-e89b-12d3-a456-426614174000'\naudio_file_path = '/path/to/audio.mp3'\n\nwith open(audio_file_path, 'rb') as audio_file:\n    files = {'audio_file': audio_file}\n    headers = {'Authorization': f'Bearer {token}'}\n    \n    res = requests.post(\n        f'https://api.sandbox.commure.com/ambient/scribe/v1/scribe/{scribe_id}/regenerate/audio',\n        headers=headers,\n        files=files\n    )\n\nresult = res.json()\nprint(f\"Regeneration started: {result['scribe_id']}\")\nprint(f\"Status: {result['status']}\")"
          }
        ]
      }
    },
    "/v1/chunking/sessions": {
      "post": {
        "summary": "Create a new chunking upload session",
        "description": "Create an upload session for chunked audio files and returns a session ID and upload instructions.\n\n## Chunk Configuration\n\n| Setting | Value | Notes |\n| --- | --- | --- |\n| **Chunk Duration** | 30 seconds | Audio duration per chunk file |\n| **Timer Interval** | 30 seconds | Flush interval for buffered audio |\n| **Final Packet Wait** | 500 ms | Wait time after stopping recorder to ensure final packets arrive |\n\n**Note:** A chunk might be smaller than 30 seconds. Every time the user pauses, the current chunk will be saved and a new one created on resume.\n\n## Implementation Details\n\n- **Chunk Duration:** 30 seconds of audio per chunk file\n- **Timer Interval:** Used to monitor each 30-second chunk and ensure the upload arrives and succeeds\n- **Final Packet Wait:** 500ms delay to wait for final audio packets after stopping recorder\n- **Completing the Session:**\n  - Call `/complete` endpoint after all chunks have been successfully uploaded\n  - If there are intentionally missing chunks that you do not want to upload, set `force_complete=true` in the request body to skip validation for those chunks\n  - If `force_complete=false` (default), the server will validate that all chunks specified in the `total_chunks` parameter are present. Missing chunks will result in an error response\n\n## Audio Formats\n\n### Supported Content Types\n\n| Format | MIME Type | Platform Support |\n| --- | --- | --- |\n| MP4 | `video/mp4` | All platforms |\n| WAV | `audio/wav` | iOS, Android (PCM 16-bit) |\n| AAC | `audio/aac` | Safari, iOS (fallback) |\n| M4A | `audio/m4a` | iOS, macOS |\n| OGG | `audio/ogg` | Web (non-Safari), iOS (preferred) |\n| WebM | `audio/webm` | Web (non-Safari) |\n\n### Platform-Specific Recommendations\n\n**Web (Non-Safari):**\n- Codec: Opus\n- Container: OGG/WebM\n- Sample Rate: 16,000 Hz\n- Bit Rate: 24,000 bps (24 kbps)\n- Channels: 1 (Mono)\n- Sample Size: 16-bit\n\n**Web (Safari):**\n- Codec: AAC\n- Container: AAC\n- Sample Rate: 48,000 Hz\n- Bit Rate: 48,000 bps (48 kbps)\n- Channels: 1 (Mono)\n- Sample Size: 16-bit\n\n**iOS (Mobile):**\n- Codec: Opus (preferred) or AAC fallback\n- Container: WAV (for chunking uploads)\n- Sample Rate: 16,000 Hz\n- Channels: 1 (Mono)\n\n**Android (Mobile):**\n- Codec: PCM 16-bit\n- Container: WAV\n- Sample Rate: 44,100 Hz (preferred), 16,000 Hz (fallback), 8,000 Hz (last resort)\n- Bit Rate: 32,000 bps\n- Channels: 1 (Mono)",
        "tags": ["Chunking"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "responses": {
          "201": {
            "description": "Upload session created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique session ID for this upload session"
                    },
                    "upload_session_status": {
                      "type": "string",
                      "enum": ["UPLOAD_STARTED"],
                      "description": "Status of the upload session"
                    },
                    "chunk_upload_info": {
                      "type": "object",
                      "properties": {
                        "upload_endpoint": {
                          "type": "string",
                          "description": "URL template for uploading chunks. Replace {chunk_num} with the chunk number (1-indexed)."
                        },
                        "method": {
                          "type": "string",
                          "enum": ["PUT"],
                          "description": "HTTP method to use for chunk uploads"
                        },
                        "content_type": {
                          "type": "string",
                          "enum": ["video/mp4", "audio/wav", "audio/aac", "audio/m4a", "audio/ogg", "audio/webm"],
                          "description": "Content type to use when uploading chunks. Supported formats: mp4 (video/mp4), wav (audio/wav), aac (audio/aac), m4a (audio/m4a), ogg (audio/ogg), webm (audio/webm)"
                        }
                      },
                      "required": ["upload_endpoint", "method", "content_type"]
                    }
                  },
                  "required": ["session_id", "upload_session_status", "chunk_upload_info"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful session creation",
                    "value": {
                      "session_id": "123e4567-e89b-12d3-a456-426614174000",
                      "upload_session_status": "UPLOAD_STARTED",
                      "chunk_upload_info": {
                        "upload_endpoint": "/v1/chunking/sessions/123e4567-e89b-12d3-a456-426614174000/chunks/{chunk_num}",
                        "method": "PUT",
                        "content_type": "audio/wav"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create upload session"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Create upload session",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Create session with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`\n  }\n});\n\nconst session = await res.json();\nconsole.log('Session ID:', session.session_id);\nconsole.log('Upload endpoint:', session.chunk_upload_info.upload_endpoint);"
          },
          {
            "lang": "Python",
            "label": "Create session with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions',\n    headers={'Authorization': f'Bearer {token}'}\n)\n\nsession = res.json()\nprint(f\"Session ID: {session['session_id']}\")\nprint(f\"Upload endpoint: {session['chunk_upload_info']['upload_endpoint']}\")"
          }
        ]
      }
    },
    "/v1/chunking/sessions/{session_id}/chunks/{chunk_num}": {
      "put": {
        "summary": "Upload an audio chunk",
        "description": "Upload a single audio chunk to the specified upload session. Chunk numbering starts at 1. Chunks may be uploaded in any order (sequential or random).",
        "tags": ["Chunking"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The upload session id obtained from creating a session",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
            "name": "chunk_num",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "The chunk number (1-indexed: 1, 2, 3, ...)",
            "example": 1
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "video/mp4": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "MP4 video chunk data"
              }
            },
            "audio/wav": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "WAV audio chunk data"
              }
            },
            "audio/aac": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "AAC audio chunk data"
              }
            },
            "audio/m4a": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "M4A audio chunk data"
              }
            },
            "audio/ogg": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "OGG audio chunk data"
              }
            },
            "audio/webm": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "WebM audio chunk data"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Chunk uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The upload session id"
                    },
                    "chunk_num": {
                      "type": "integer",
                      "description": "The chunk number that was uploaded"
                    },
                    "file_size": {
                      "type": "integer",
                      "description": "Size of the uploaded chunk in bytes"
                    }
                  },
                  "required": ["session_id", "chunk_num", "file_size"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful chunk upload",
                    "value": {
                      "session_id": "123e4567-e89b-12d3-a456-426614174000",
                      "chunk_num": 1,
                      "file_size": 1048576
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error - invalid chunk number or session id format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_chunk_num": {
                    "value": {
                      "detail": "Invalid chunk_num: 0 (must be >= 1) for session 123e4567-e89b-12d3-a456-426614174000"
                    }
                  },
                  "invalid_session_id": {
                    "value": {
                      "detail": "Invalid session_id format: invalid-uuid"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to upload chunk"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Upload chunk",
            "source": "curl -X PUT https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/123e4567-e89b-12d3-a456-426614174000/chunks/1 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: audio/wav' \\\n  --data-binary @chunk1.wav"
          },
          {
            "lang": "JavaScript",
            "label": "Upload chunk with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst sessionToken = '123e4567-e89b-12d3-a456-426614174000';\nconst chunkNum = 1;\nconst chunkData = new Uint8Array([/* chunk bytes */]);\n// Or read from file: const chunkData = await fs.readFile('chunk1.wav');\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/${sessionToken}/chunks/${chunkNum}`,\n  {\n    method: 'PUT',\n    headers: {\n      'Authorization': `Bearer ${token}`,\n      'Content-Type': 'audio/wav'\n    },\n    body: chunkData\n  }\n);\n\nconst result = await res.json();\nconsole.log(`Chunk ${result.chunk_num} uploaded: ${result.file_size} bytes`);"
          },
          {
            "lang": "Python",
            "label": "Upload chunk with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\nsession_token = '123e4567-e89b-12d3-a456-426614174000'\nchunk_num = 1\n\n# Read chunk data from file\nwith open('chunk1.wav', 'rb') as chunk_file:\n    chunk_data = chunk_file.read()\n    \n    res = requests.put(\n        f'https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/{session_token}/chunks/{chunk_num}',\n        headers={\n            'Authorization': f'Bearer {token}',\n            'Content-Type': 'audio/wav'\n        },\n        data=chunk_data\n    )\n\nresult = res.json()\nprint(f\"Chunk {result['chunk_num']} uploaded: {result['file_size']} bytes\")"
          }
        ]
      }
    },
    "/v1/chunking/sessions/{session_id}/complete": {
      "post": {
        "summary": "Complete an upload session",
        "description": "Mark an upload session as complete and trigger transcription processing. This endpoint should only be called after all chunks have been uploaded. The server collects all uploaded chunks, validates that no chunks are missing (unless force_complete is true), combines them in order, and triggers the transcription workflow.",
        "tags": ["Chunking"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The upload session id obtained from creating a session",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "total_chunks": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Total number of chunks that were uploaded",
                    "example": 5
                  },
                  "force_complete": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, skip validation for missing chunks and proceed with completion and transcription",
                    "example": false
                  }
                },
                "required": ["total_chunks"]
              },
              "examples": {
                "standard": {
                  "summary": "Standard completion",
                  "value": {
                    "total_chunks": 5,
                    "force_complete": false
                  }
                },
                "force_complete": {
                  "summary": "Force completion with missing chunks",
                  "value": {
                    "total_chunks": 5,
                    "force_complete": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Session completion accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Upload session id"
                    },
                    "total_chunks": {
                      "type": "integer",
                      "description": "Total chunks declared for this session"
                    },
                    "status": {
                      "type": "string",
                      "description": "Final upload session status",
                      "example": "UPLOAD_COMPLETED"
                    },
                    "transcription_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Transcription ID"
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when upload session was completed"
                    }
                  },
                  "required": ["session_id", "total_chunks", "status", "transcription_id", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Successful completion",
                    "value": {
                      "session_id": "123e4567-e89b-12d3-a456-426614174000",
                      "total_chunks": 5,
                      "status": "UPLOAD_COMPLETED",
                      "transcription_id": "223e4567-e89b-12d3-a456-426614174001",
                      "submitted_at": "2025-01-02T10:35:00Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Session not found or doesn't belong to user's account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Session not found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error - invalid session id format or missing chunks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_session_id": {
                    "value": {
                      "detail": "Invalid session_id format: invalid-uuid"
                    }
                  },
                  "missing_chunks": {
                    "value": {
                      "detail": "Missing chunks detected. Expected 5 chunks but only 4 found."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to complete upload session"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Complete upload session",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/123e4567-e89b-12d3-a456-426614174000/complete \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"total_chunks\": 5,\n    \"force_complete\": false\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Complete session with fetch",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst sessionToken = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/${sessionToken}/complete`,\n  {\n    method: 'POST',\n    headers: {\n      'Authorization': `Bearer ${token}`,\n      'Content-Type': 'application/json'\n    },\n    body: JSON.stringify({\n      total_chunks: 5,\n      force_complete: false\n    })\n  }\n);\n\nconst result = await res.json();\nconsole.log(`Session ${result.session_id} completed with ${result.total_chunks} chunks`);\nconsole.log(`Transcription ID: ${result.transcription_id}`);\nconsole.log(`Submitted at: ${result.submitted_at}`);"
          },
          {
            "lang": "Python",
            "label": "Complete session with requests",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\nsession_token = '123e4567-e89b-12d3-a456-426614174000'\n\ndata = {\n    'total_chunks': 5,\n    'force_complete': False\n}\n\nres = requests.post(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/chunking/sessions/{session_token}/complete',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'Content-Type': 'application/json'\n    },\n    json=data\n)\n\nresult = res.json()\nprint(f\"Session {result['session_id']} completed with {result['total_chunks']} chunks\")\nprint(f\"Status: {result['status']}\")\nprint(f\"Transcription ID: {result['transcription_id']}\")\nprint(f\"Submitted at: {result['submitted_at']}\")"
          }
        ]
      }
    },
    "/v1/corrections": {
      "post": {
        "summary": "Create a new spell correction",
        "description": "Create a new correction mapping for misspelled text. Corrections can be user-specific or global, and are used to improve transcription accuracy.",
        "tags": ["corrections"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user-uuid",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "User UUID for authentication and ownership",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["misspelled_text", "correct_text", "correction_type"],
                "properties": {
                  "misspelled_text": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The misspelled or incorrect text",
                    "example": "tylenol"
                  },
                  "correct_text": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The correct text",
                    "example": "ACETAMINOPHEN"
                  },
                  "correction_type": {
                    "type": "string",
                    "enum": ["PRESCRIPTION", "DISEASE", "MEDICAL_EQUIPMENT", "MEDICAL_PROCEDURE", "MEDICAL_CONDITION", "OTHER", "ACRONYM"],
                    "description": "Type of correction",
                    "example": "PRESCRIPTION"
                  }
                }
              },
              "examples": {
                "prescription": {
                  "summary": "Prescription correction",
                  "value": {
                    "misspelled_text": "tylenol",
                    "correct_text": "ACETAMINOPHEN",
                    "correction_type": "PRESCRIPTION"
                  }
                },
                "disease": {
                  "summary": "Disease correction",
                  "value": {
                    "misspelled_text": "diabeetes",
                    "correct_text": "DIABETES",
                    "correction_type": "DISEASE"
                  }
                },
                "acronym": {
                  "summary": "Acronym correction",
                  "value": {
                    "misspelled_text": "cardiopulmonary resuscitation",
                    "correct_text": "CPR",
                    "correction_type": "ACRONYM"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Correction created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectionResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "misspelled_text": "tylenol",
                      "correct_text": "ACETAMINOPHEN",
                      "correction_type": "PRESCRIPTION",
                      "is_user_specific": false,
                      "occurrence_count": 1,
                      "correction_count": 0,
                      "active": true,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user_uuid format"
                    }
                  },
                  "validation_error": {
                    "value": {
                      "detail": "Validation error message"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - user is inactive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "inactive_user": {
                    "value": {
                      "detail": "User is inactive"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "user_not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict - correction may already exist",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "duplicate": {
                    "value": {
                      "detail": "Database constraint violation - correction may already exist"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create correction"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Create correction",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/corrections \\\n  -H 'Content-Type: application/json' \\\n  -H 'user-uuid: 123e4567-e89b-12d3-a456-426614174000' \\\n  -d '{\n    \"misspelled_text\": \"tylenol\",\n    \"correct_text\": \"ACETAMINOPHEN\",\n    \"correction_type\": \"PRESCRIPTION\"\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Create correction with fetch",
            "source": "const userId = '123e4567-e89b-12d3-a456-426614174000';\nconst correction = {\n  misspelled_text: 'tylenol',\n  correct_text: 'ACETAMINOPHEN',\n  correction_type: 'PRESCRIPTION'\n};\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/corrections', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'user-uuid': userId\n  },\n  body: JSON.stringify(correction)\n});\n\nconst created = await res.json();\nconsole.log('Created correction:', created.id);"
          },
          {
            "lang": "Python",
            "label": "Create correction with requests",
            "source": "import requests\n\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\ncorrection = {\n    'misspelled_text': 'tylenol',\n    'correct_text': 'ACETAMINOPHEN',\n    'correction_type': 'PRESCRIPTION'\n}\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/corrections',\n    headers={'user-uuid': user_id},\n    json=correction\n)\n\ncreated = res.json()\nprint(f\"Created correction: {created['id']}\")"
          }
        ]
      },
      "get": {
        "summary": "Get all corrections for a user",
        "description": "Retrieve all corrections for the authenticated user. Can filter to show only active corrections or include inactive ones.",
        "tags": ["corrections"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user-uuid",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "User UUID for authentication and ownership",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
            "name": "active_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "If true, only return active corrections. Defaults to true.",
            "example": true
          }
        ],
        "responses": {
          "200": {
            "description": "Corrections retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "corrections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CorrectionResponse"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of corrections returned"
                    }
                  },
                  "required": ["corrections", "total"]
                },
                "examples": {
                  "success": {
                    "value": {
                      "corrections": [
                        {
                          "id": "550e8400-e29b-41d4-a716-446655440000",
                          "misspelled_text": "tylenol",
                          "correct_text": "ACETAMINOPHEN",
                          "correction_type": "PRESCRIPTION",
                          "is_user_specific": false,
                          "occurrence_count": 5,
                          "correction_count": 3,
                          "active": true,
                          "created_at": "2025-01-02T10:30:00Z",
                          "updated_at": "2025-01-02T10:35:00Z"
                        },
                        {
                          "id": "550e8400-e29b-41d4-a716-446655440001",
                          "misspelled_text": "diabeetes",
                          "correct_text": "DIABETES",
                          "correction_type": "DISEASE",
                          "is_user_specific": true,
                          "occurrence_count": 2,
                          "correction_count": 2,
                          "active": true,
                          "created_at": "2025-01-01T08:00:00Z",
                          "updated_at": "2025-01-01T08:00:00Z"
                        }
                      ],
                      "total": 2
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid user UUID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user_uuid format"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - user is inactive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "inactive_user": {
                    "value": {
                      "detail": "User is inactive"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "user_not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to get corrections"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get all active corrections",
            "source": "curl -X GET 'https://api.sandbox.commure.com/ambient/scribe/v1/corrections?active_only=true' \\\n  -H 'user-uuid: 123e4567-e89b-12d3-a456-426614174000'"
          },
          {
            "lang": "cURL",
            "label": "Get all corrections including inactive",
            "source": "curl -X GET 'https://api.sandbox.commure.com/ambient/scribe/v1/corrections?active_only=false' \\\n  -H 'user-uuid: 123e4567-e89b-12d3-a456-426614174000'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch corrections",
            "source": "const userId = '123e4567-e89b-12d3-a456-426614174000';\nconst activeOnly = true;\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/corrections?active_only=${activeOnly}`,\n  {\n    headers: {\n      'user-uuid': userId\n    }\n  }\n);\n\nconst {corrections, total} = await res.json();\nconsole.log(`Found ${total} corrections`);\ncorrections.forEach(c => {\n  console.log(`${c.misspelled_text} -> ${c.correct_text} (${c.correction_type})`);\n});"
          },
          {
            "lang": "Python",
            "label": "Get corrections with requests",
            "source": "import requests\n\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\nactive_only = True\n\nres = requests.get(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/corrections?active_only={active_only}',\n    headers={'user-uuid': user_id}\n)\n\ndata = res.json()\nprint(f\"Found {data['total']} corrections\")\nfor correction in data['corrections']:\n    print(f\"{correction['misspelled_text']} -> {correction['correct_text']} ({correction['correction_type']})\")"
          }
        ]
      }
    },
    "/v1/corrections/{correction_id}": {
      "patch": {
        "summary": "Update a correction",
        "description": "Update an existing correction's correct text or correction type. Only corrections belonging to the authenticated user can be updated.",
        "tags": ["corrections"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user-uuid",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "User UUID for authentication and ownership",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
            "name": "correction_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the correction to update",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "correct_text": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The correct text (optional)",
                    "example": "ACETAMINOPHEN 500MG"
                  },
                  "correction_type": {
                    "type": "string",
                    "enum": ["PRESCRIPTION", "DISEASE", "MEDICAL_EQUIPMENT", "MEDICAL_PROCEDURE", "MEDICAL_CONDITION", "OTHER", "ACRONYM"],
                    "description": "Type of correction (optional)",
                    "example": "PRESCRIPTION"
                  }
                }
              },
              "examples": {
                "update_text": {
                  "summary": "Update correct text",
                  "value": {
                    "correct_text": "ACETAMINOPHEN 500MG"
                  }
                },
                "update_type": {
                  "summary": "Update correction type",
                  "value": {
                    "correction_type": "PRESCRIPTION"
                  }
                },
                "update_both": {
                  "summary": "Update both fields",
                  "value": {
                    "correct_text": "ACETAMINOPHEN 500MG",
                    "correction_type": "PRESCRIPTION"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Correction updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectionResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "misspelled_text": "tylenol",
                      "correct_text": "ACETAMINOPHEN 500MG",
                      "correction_type": "PRESCRIPTION",
                      "is_user_specific": false,
                      "occurrence_count": 5,
                      "correction_count": 3,
                      "active": true,
                      "created_at": "2025-01-02T10:30:00Z",
                      "updated_at": "2025-01-02T11:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user_uuid format"
                    }
                  },
                  "validation_error": {
                    "value": {
                      "detail": "Validation error message"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - user is inactive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "inactive_user": {
                    "value": {
                      "detail": "User is inactive"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Correction not found or access denied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Correction not found"
                    }
                  },
                  "access_denied": {
                    "value": {
                      "detail": "Access denied to this correction"
                    }
                  },
                  "user_not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to update correction"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Update correction",
            "source": "curl -X PATCH https://api.sandbox.commure.com/ambient/scribe/v1/corrections/550e8400-e29b-41d4-a716-446655440000 \\\n  -H 'Content-Type: application/json' \\\n  -H 'user-uuid: 123e4567-e89b-12d3-a456-426614174000' \\\n  -d '{\n    \"correct_text\": \"ACETAMINOPHEN 500MG\",\n    \"correction_type\": \"PRESCRIPTION\"\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Update correction with fetch",
            "source": "const userId = '123e4567-e89b-12d3-a456-426614174000';\nconst correctionId = '550e8400-e29b-41d4-a716-446655440000';\nconst updates = {\n  correct_text: 'ACETAMINOPHEN 500MG',\n  correction_type: 'PRESCRIPTION'\n};\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/corrections/${correctionId}`,\n  {\n    method: 'PATCH',\n    headers: {\n      'Content-Type': 'application/json',\n      'user-uuid': userId\n    },\n    body: JSON.stringify(updates)\n  }\n);\n\nconst updated = await res.json();\nconsole.log('Updated correction:', updated.id);"
          },
          {
            "lang": "Python",
            "label": "Update correction with requests",
            "source": "import requests\n\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\ncorrection_id = '550e8400-e29b-41d4-a716-446655440000'\nupdates = {\n    'correct_text': 'ACETAMINOPHEN 500MG',\n    'correction_type': 'PRESCRIPTION'\n}\n\nres = requests.patch(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/corrections/{correction_id}',\n    headers={'user-uuid': user_id},\n    json=updates\n)\n\nupdated = res.json()\nprint(f\"Updated correction: {updated['id']}\")"
          }
        ]
      },
      "delete": {
        "summary": "Delete a correction",
        "description": "Mark a correction as inactive (soft delete). Only corrections belonging to the authenticated user can be deleted.",
        "tags": ["corrections"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user-uuid",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "User UUID for authentication and ownership",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
            "name": "correction_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the correction to delete",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "responses": {
          "204": {
            "description": "Correction deleted successfully (no content)"
          },
          "400": {
            "description": "Bad request - invalid user UUID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user_uuid format"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - user is inactive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "inactive_user": {
                    "value": {
                      "detail": "User is inactive"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Correction not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Correction not found"
                    }
                  },
                  "user_not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to delete correction"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Delete correction",
            "source": "curl -X DELETE https://api.sandbox.commure.com/ambient/scribe/v1/corrections/550e8400-e29b-41d4-a716-446655440000 \\\n  -H 'user-uuid: 123e4567-e89b-12d3-a456-426614174000'"
          },
          {
            "lang": "JavaScript",
            "label": "Delete correction with fetch",
            "source": "const userId = '123e4567-e89b-12d3-a456-426614174000';\nconst correctionId = '550e8400-e29b-41d4-a716-446655440000';\n\nconst res = await fetch(\n  `https://api.sandbox.commure.com/ambient/scribe/v1/corrections/${correctionId}`,\n  {\n    method: 'DELETE',\n    headers: {\n      'user-uuid': userId\n    }\n  }\n);\n\nif (res.status === 204) {\n  console.log('Correction deleted successfully');\n} else {\n  const error = await res.json();\n  console.error('Error:', error.detail);\n}"
          },
          {
            "lang": "Python",
            "label": "Delete correction with requests",
            "source": "import requests\n\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\ncorrection_id = '550e8400-e29b-41d4-a716-446655440000'\n\nres = requests.delete(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/corrections/{correction_id}',\n    headers={'user-uuid': user_id}\n)\n\nif res.status_code == 204:\n    print('Correction deleted successfully')\nelse:\n    print(f\"Error: {res.json()['detail']}\")"
          }
        ]
      }
    },
    "/v1/users": {
      "get": {
        "summary": "List all users",
        "description": "Retrieve all users associated with the authenticated service account.",
        "tags": ["users"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "responses": {
          "200": {
            "description": "Users retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "UUID of the user"
                          },
                          "external_id": {
                            "type": "string",
                            "description": "External identifier for the user"
                          },
                          "is_active": {
                            "type": "boolean",
                            "description": "Whether the user is active"
                          }
                        },
                        "required": ["user_id", "external_id", "is_active"]
                      },
                      "description": "List of users for the service account"
                    }
                  },
                  "required": ["users"]
                },
                "examples": {
                  "multiple_users": {
                    "summary": "Service account with multiple users",
                    "value": {
                      "users": [
                        {
                          "user_id": "123e4567-e89b-12d3-a456-426614174000",
                          "external_id": "user@hospital.com",
                          "is_active": true
                        },
                        {
                          "user_id": "987e6543-e21b-12d3-a456-426614174001",
                          "external_id": "doctor@hospital.com",
                          "is_active": true
                        },
                        {
                          "user_id": "456e7890-e89b-12d3-a456-426614174002",
                          "external_id": "inactive@hospital.com",
                          "is_active": false
                        }
                      ]
                    }
                  },
                  "empty_list": {
                    "summary": "No users yet",
                    "value": {
                      "users": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - not a service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_service_account": {
                    "value": {
                      "detail": "Only service accounts can access this endpoint"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to retrieve users"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "List users",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/users \\\n  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Fetch users",
            "source": "const token = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN';\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/users', {\n  method: 'GET',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito'\n  }\n});\n\nconst {users} = await res.json();\nconsole.log(`Found ${users.length} users`);"
          },
          {
            "lang": "Python",
            "label": "Get users list",
            "source": "import requests\n\ntoken = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN'\n\nres = requests.get(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/users',\n    headers={'Authorization': f'Bearer {token}', 'auth-scheme': 'cognito'}\n)\n\ndata = res.json()\nprint(f\"Found {len(data['users'])} users\")\nfor user in data['users']:\n    print(f\"  - {user['external_id']} ({user['user_id']}): active={user['is_active']}\")"
          }
        ]
      }
    },
    "/v1/users/create": {
      "post": {
        "summary": "Create a new user",
        "description": "Create a new user associated with the authenticated service account. Each user must have a unique external_id.",
        "tags": ["users"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "external_id": {
                    "type": "string",
                    "minLength": 1,
                    "description": "External identifier for the user (e.g., email, employee ID, or system-specific ID). Must be unique across all users."
                  }
                },
                "required": ["external_id"]
              },
              "examples": {
                "email": {
                  "summary": "Using email as external ID",
                  "value": {
                    "external_id": "doctor@hospital.com"
                  }
                },
                "employee_id": {
                  "summary": "Using employee ID",
                  "value": {
                    "external_id": "EMP-12345"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUID of the created user"
                    }
                  },
                  "required": ["user_id"]
                },
                "examples": {
                  "success": {
                    "summary": "User created",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - user already exists or invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "duplicate_user": {
                    "summary": "User already exists",
                    "value": {
                      "detail": "User with this external_id already exists"
                    }
                  },
                  "empty_external_id": {
                    "summary": "Empty external_id",
                    "value": {
                      "detail": "external_id cannot be empty"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - not a service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_service_account": {
                    "value": {
                      "detail": "Only service accounts can access this endpoint"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create user"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Create user",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/users/create \\\n  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"external_id\": \"doctor@hospital.com\"}'"
          },
          {
            "lang": "JavaScript",
            "label": "Create user",
            "source": "const token = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN';\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/users/create', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    external_id: 'doctor@hospital.com'\n  })\n});\n\nconst {user_id} = await res.json();\nconsole.log('Created user:', user_id);"
          },
          {
            "lang": "Python",
            "label": "Create user",
            "source": "import requests\n\ntoken = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN'\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/users/create',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'auth-scheme': 'cognito'\n    },\n    json={'external_id': 'doctor@hospital.com'}\n)\n\ndata = res.json()\nprint(f\"Created user with ID: {data['user_id']}\")"
          }
        ]
      }
    },
    "/v1/users/{user_id}": {
      "get": {
        "summary": "Get user by UUID",
        "description": "Retrieve a specific user by their UUID. The user must belong to the authenticated service account.",
        "tags": ["users"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the user to retrieve",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "responses": {
          "200": {
            "description": "User retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUID of the user"
                    },
                    "external_id": {
                      "type": "string",
                      "description": "External identifier for the user"
                    },
                    "is_active": {
                      "type": "boolean",
                      "description": "Whether the user is active"
                    }
                  },
                  "required": ["user_id", "external_id", "is_active"]
                },
                "examples": {
                  "active_user": {
                    "summary": "Active user",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000",
                      "external_id": "doctor@hospital.com",
                      "is_active": true
                    }
                  },
                  "inactive_user": {
                    "summary": "Inactive user",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000",
                      "external_id": "former_doctor@hospital.com",
                      "is_active": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid UUID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user ID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - not a service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_service_account": {
                    "value": {
                      "detail": "Only service accounts can access this endpoint"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found or not owned by service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to retrieve user"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get user by UUID",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/users/123e4567-e89b-12d3-a456-426614174000 \\\n  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Get user",
            "source": "const token = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN';\nconst userId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch(`https://api.sandbox.commure.com/ambient/scribe/v1/users/${userId}`, {\n  method: 'GET',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito'\n  }\n});\n\nconst user = await res.json();\nconsole.log('User:', user);"
          },
          {
            "lang": "Python",
            "label": "Get user by UUID",
            "source": "import requests\n\ntoken = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN'\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\n\nres = requests.get(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/users/{user_id}',\n    headers={'Authorization': f'Bearer {token}', 'auth-scheme': 'cognito'}\n)\n\nuser = res.json()\nprint(f\"User: {user['external_id']} - Active: {user['is_active']}\")"
          }
        ]
      },
      "put": {
        "summary": "Update user status",
        "description": "Update a user's active status.",
        "tags": ["users"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the user to update",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "is_active": {
                    "type": "boolean",
                    "description": "Whether the user should be active or inactive"
                  }
                },
                "required": ["is_active"]
              },
              "examples": {
                "deactivate": {
                  "summary": "Deactivate user",
                  "value": {
                    "is_active": false
                  }
                },
                "activate": {
                  "summary": "Activate user",
                  "value": {
                    "is_active": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUID of the user"
                    },
                    "external_id": {
                      "type": "string",
                      "description": "External identifier for the user"
                    },
                    "is_active": {
                      "type": "boolean",
                      "description": "Updated active status"
                    }
                  },
                  "required": ["user_id", "external_id", "is_active"]
                },
                "examples": {
                  "deactivated": {
                    "summary": "User deactivated",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000",
                      "external_id": "doctor@hospital.com",
                      "is_active": false
                    }
                  },
                  "activated": {
                    "summary": "User activated",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000",
                      "external_id": "doctor@hospital.com",
                      "is_active": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid UUID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid user ID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - not a service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_service_account": {
                    "value": {
                      "detail": "Only service accounts can access this endpoint"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found or not owned by service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to update user"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Deactivate user",
            "source": "curl -X PUT https://api.sandbox.commure.com/ambient/scribe/v1/users/123e4567-e89b-12d3-a456-426614174000 \\\n  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"is_active\": false}'"
          },
          {
            "lang": "JavaScript",
            "label": "Update user status",
            "source": "const token = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN';\nconst userId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch(`https://api.sandbox.commure.com/ambient/scribe/v1/users/${userId}`, {\n  method: 'PUT',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    is_active: false\n  })\n});\n\nconst user = await res.json();\nconsole.log('Updated user:', user);"
          },
          {
            "lang": "Python",
            "label": "Update user status",
            "source": "import requests\n\ntoken = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN'\nuser_id = '123e4567-e89b-12d3-a456-426614174000'\n\nres = requests.put(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/users/{user_id}',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'auth-scheme': 'cognito'\n    },\n    json={'is_active': False}\n)\n\nuser = res.json()\nprint(f\"User {user['external_id']} is now {'active' if user['is_active'] else 'inactive'}\")"
          }
        ]
      }
    },
    "/v1/users/external-id/{external_id}": {
      "get": {
        "summary": "Get user by external ID",
        "description": "Retrieve a specific user by their external identifier. The user must belong to the authenticated service account.",
        "tags": ["users"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The external identifier of the user to retrieve (e.g., email, employee ID)",
            "example": "doctor@hospital.com"
          }
        ],
        "responses": {
          "200": {
            "description": "User retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUID of the user"
                    },
                    "external_id": {
                      "type": "string",
                      "description": "External identifier for the user"
                    },
                    "is_active": {
                      "type": "boolean",
                      "description": "Whether the user is active"
                    }
                  },
                  "required": ["user_id", "external_id", "is_active"]
                },
                "examples": {
                  "active_user": {
                    "summary": "Active user found",
                    "value": {
                      "user_id": "123e4567-e89b-12d3-a456-426614174000",
                      "external_id": "doctor@hospital.com",
                      "is_active": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - not a service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_service_account": {
                    "value": {
                      "detail": "Only service accounts can access this endpoint"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found or not owned by service account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "User not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to retrieve user"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get user by external ID",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/users/external-id/doctor@hospital.com \\\n  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Get user by external ID",
            "source": "const token = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN';\nconst externalId = 'doctor@hospital.com';\n\nconst res = await fetch(`https://api.sandbox.commure.com/ambient/scribe/v1/users/external-id/${encodeURIComponent(externalId)}`, {\n  method: 'GET',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito'\n  }\n});\n\nconst user = await res.json();\nconsole.log('Found user:', user);"
          },
          {
            "lang": "Python",
            "label": "Get user by external ID",
            "source": "import requests\nfrom urllib.parse import quote\n\ntoken = 'YOUR_SERVICE_ACCOUNT_JWT_TOKEN'\nexternal_id = 'doctor@hospital.com'\n\nres = requests.get(\n    f'https://api.sandbox.commure.com/ambient/scribe/v1/users/external-id/{quote(external_id)}',\n    headers={'Authorization': f'Bearer {token}', 'auth-scheme': 'cognito'}\n)\n\nuser = res.json()\nprint(f\"User UUID: {user['user_id']}\")\nprint(f\"External ID: {user['external_id']}\")\nprint(f\"Active: {user['is_active']}\")"
          }
        ]
      }
    },
    "/v1/summaries": {
      "post": {
        "summary": "Submit text for AI summarization",
        "description": "Submit text for asynchronous AI summarization using a specified template.",
        "tags": ["summaries"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/authSchemeHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Text to summarize (e.g., clinical notes, conversation transcript, medical documentation)"
                  },
                  "template_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUID of the template to use for summary generation. Must be associated with your account."
                  }
                },
                "required": ["text", "template_id"]
              },
              "examples": {
                "clinical_note": {
                  "summary": "Clinical note summarization",
                  "value": {
                    "text": "Patient presents with chief complaint of persistent cough for the past two weeks. Patient reports the cough is dry and worse at night. No fever, no shortness of breath. Patient denies any recent travel or sick contacts. On examination, lungs are clear to auscultation bilaterally. Vital signs are within normal limits. Assessment: Upper respiratory tract infection. Plan: Recommend over-the-counter cough suppressant, increase fluid intake, and follow up if symptoms worsen or persist beyond one week.",
                    "template_id": "123e4567-e89b-12d3-a456-426614174000"
                  }
                },
                "transcription_summary": {
                  "summary": "Transcription summary",
                  "value": {
                    "text": "Doctor: Good morning, how are you feeling today? Patient: Not great, I've had this cough for about two weeks now. Doctor: Tell me more about it. Patient: It's a dry cough, and it gets really bad at night...",
                    "template_id": "987e6543-e21b-12d3-a456-426614174001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Summary request accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique identifier for this summary. Use this to check summary status."
                    },
                    "status": {
                      "type": "string",
                      "enum": ["IN_PROGRESS", "COMPLETED", "ERROR"],
                      "description": "Initial status of the summary (typically IN_PROGRESS)"
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Timestamp when summary was submitted"
                    }
                  },
                  "required": ["summary_id", "status", "submitted_at"]
                },
                "examples": {
                  "success": {
                    "summary": "Summary submission accepted",
                    "value": {
                      "summary_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "IN_PROGRESS",
                      "submitted_at": "2025-01-21T10:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "empty_text": {
                    "summary": "Empty text provided",
                    "value": {
                      "detail": "text field cannot be empty"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found or not associated with your account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "template_not_found": {
                    "value": {
                      "detail": "Template with id 123e4567-e89b-12d3-a456-426614174000 not found or does not belong to scribe account"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to create summary workflow"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Submit text for summary",
            "source": "curl -X POST https://api.sandbox.commure.com/ambient/scribe/v1/summaries \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"text\": \"Patient presents with...\",\n    \"template_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n  }'"
          },
          {
            "lang": "JavaScript",
            "label": "Submit for summarization",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst templateId = '123e4567-e89b-12d3-a456-426614174000';\n\nconst res = await fetch('https://api.sandbox.commure.com/ambient/scribe/v1/summaries', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`,\n    'auth-scheme': 'cognito',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n    text: 'Patient presents with chief complaint of persistent cough...',\n    template_id: templateId\n  })\n});\n\nconst {summary_id, status, submitted_at} = await res.json();\nconsole.log('Summary ID:', summary_id);\nconsole.log('Status:', status);\nconsole.log('Submitted at:', submitted_at);"
          },
          {
            "lang": "Python",
            "label": "Submit for summarization",
            "source": "import requests\n\ntoken = 'YOUR_JWT_TOKEN'\ntemplate_id = '123e4567-e89b-12d3-a456-426614174000'\n\nres = requests.post(\n    'https://api.sandbox.commure.com/ambient/scribe/v1/summaries',\n    headers={\n        'Authorization': f'Bearer {token}',\n        'auth-scheme': 'cognito'\n    },\n    json={\n        'text': 'Patient presents with chief complaint of persistent cough...',\n        'template_id': template_id\n    }\n)\n\ndata = res.json()\nprint(f\"Summary ID: {data['summary_id']}\")\nprint(f\"Status: {data['status']}\")\nprint(f\"Submitted at: {data['submitted_at']}\")"
          }
        ]
      }
    },
    "/v1/summaries/{summary_id}": {
      "get": {
        "summary": "Get summary status and results",
        "description": "Retrieve the status and results of a summary generation request.",
        "tags": ["summaries"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/authSchemeHeader" },
          {
            "name": "summary_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The UUID of the summary to retrieve",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "responses": {
          "200": {
            "description": "Summary details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique summary identifier"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["IN_PROGRESS", "COMPLETED", "ERROR"],
                      "description": "Current status:\n- `IN_PROGRESS`: AI is generating the summary\n- `COMPLETED`: Summary generation successful, results available\n- `ERROR`: Summary generation failed"
                    },
                    "input_text": {
                      "type": "string",
                      "description": "The original text that was submitted for summarization"
                    },
                    "ai_task": {
                      "type": "object",
                      "nullable": true,
                      "description": "Generated summary output (null if still processing or error occurred)",
                      "properties": {
                        "template_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "Template ID used for generation"
                        },
                        "template_name": {
                          "type": "string",
                          "nullable": true,
                          "description": "Name of the template used"
                        },
                        "note_json": {
                          "type": "object",
                          "nullable": true,
                          "description": "Structured summary output in JSON format"
                        },
                        "note_text": {
                          "type": "string",
                          "nullable": true,
                          "description": "Plain text summary output"
                        }
                      }
                    },
                    "citations": {
                      "type": "object",
                      "nullable": true,
                      "description": "Generated citations for the summary (if available)",
                      "properties": {
                        "template_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "template_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "note_json": {
                          "type": "object",
                          "nullable": true,
                          "description": "Structured citations in JSON format"
                        },
                        "note_text": {
                          "type": "string",
                          "nullable": true,
                          "description": "Plain text citations"
                        }
                      }
                    },
                    "error_message": {
                      "type": "string",
                      "nullable": true,
                      "description": "Error details if status is ERROR"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the summary was created"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the summary was last updated"
                    }
                  },
                  "required": ["summary_id", "status", "input_text", "created_at", "updated_at"]
                },
                "examples": {
                  "completed": {
                    "summary": "Completed summary with results",
                    "value": {
                      "summary_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "COMPLETED",
                      "input_text": "Patient presents with chief complaint of persistent cough for the past two weeks. Patient reports the cough is dry and worse at night. No fever, no shortness of breath. Patient denies any recent travel or sick contacts. On examination, lungs are clear to auscultation bilaterally. Vital signs are within normal limits. Assessment: Upper respiratory tract infection. Plan: Recommend over-the-counter cough suppressant, increase fluid intake, and follow up if symptoms worsen or persist beyond one week.",
                      "ai_task": {
                        "template_id": "123e4567-e89b-12d3-a456-426614174000",
                        "template_name": "Clinical Note Template",
                        "note_json": {
                          "chief_complaint": "Persistent dry cough for 2 weeks",
                          "history_of_present_illness": "Patient reports dry cough worse at night. No fever, shortness of breath, or sick contacts.",
                          "physical_examination": "Lungs clear bilaterally. Vital signs normal.",
                          "assessment": "Upper respiratory tract infection",
                          "plan": "OTC cough suppressant, increase fluids, follow up if symptoms persist >1 week"
                        },
                        "note_text": "Chief Complaint: Persistent dry cough for 2 weeks\n\nHistory of Present Illness: Patient reports dry cough worse at night. No fever, shortness of breath, or sick contacts.\n\nPhysical Examination: Lungs clear bilaterally. Vital signs normal.\n\nAssessment: Upper respiratory tract infection\n\nPlan: OTC cough suppressant, increase fluids, follow up if symptoms persist >1 week"
                      },
                      "citations": {
                        "template_id": "987e6543-e21b-12d3-a456-426614174001",
                        "template_name": "Citations Template",
                        "note_json": {
                          "chief_complaint_citation": "Patient presents with chief complaint of persistent cough for the past two weeks.",
                          "symptoms_citation": "Patient reports the cough is dry and worse at night. No fever, no shortness of breath."
                        },
                        "note_text": "[Chief Complaint]: \"Patient presents with chief complaint of persistent cough for the past two weeks.\"\n[Symptoms]: \"Patient reports the cough is dry and worse at night. No fever, no shortness of breath.\""
                      },
                      "error_message": null,
                      "created_at": "2025-01-21T10:30:00Z",
                      "updated_at": "2025-01-21T10:32:15Z"
                    }
                  },
                  "in_progress": {
                    "summary": "Summary still processing",
                    "value": {
                      "summary_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "IN_PROGRESS",
                      "input_text": "Patient presents with chief complaint of persistent cough...",
                      "ai_task": null,
                      "citations": null,
                      "error_message": null,
                      "created_at": "2025-01-21T10:30:00Z",
                      "updated_at": "2025-01-21T10:30:30Z"
                    }
                  },
                  "error": {
                    "summary": "Summary generation failed",
                    "value": {
                      "summary_id": "123e4567-e89b-12d3-a456-426614174000",
                      "status": "ERROR",
                      "input_text": "Patient presents with chief complaint of persistent cough...",
                      "ai_task": null,
                      "citations": null,
                      "error_message": "AI model timeout - please retry",
                      "created_at": "2025-01-21T10:30:00Z",
                      "updated_at": "2025-01-21T10:35:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid summary ID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "invalid_uuid": {
                    "value": {
                      "detail": "Invalid summary ID format"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "detail": "Not authenticated"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Summary not found or not accessible",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "detail": "Summary not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": { "type": "string" }
                  }
                },
                "examples": {
                  "server_error": {
                    "value": {
                      "detail": "Failed to retrieve summary"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "Get summary status",
            "source": "curl -X GET https://api.sandbox.commure.com/ambient/scribe/v1/summaries/123e4567-e89b-12d3-a456-426614174000 \\\n  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n  -H 'auth-scheme: cognito'"
          },
          {
            "lang": "JavaScript",
            "label": "Poll for completion",
            "source": "const token = 'YOUR_JWT_TOKEN';\nconst summaryId = '123e4567-e89b-12d3-a456-426614174000';\n\n// Poll until completed\nlet summary;\nwhile (true) {\n  const res = await fetch(`https://api.sandbox.commure.com/ambient/scribe/v1/summaries/${summaryId}`, {\n    method: 'GET',\n    headers: {\n      'Authorization': `Bearer ${token}`,\n      'auth-scheme': 'cognito'\n    }\n  });\n  \n  summary = await res.json();\n  console.log('Status:', summary.status);\n  \n  if (summary.status === 'COMPLETED') {\n    console.log('Summary text:', summary.ai_task?.note_text);\n    break;\n  } else if (summary.status === 'ERROR') {\n    console.error('Error:', summary.error_message);\n    break;\n  }\n  \n  // Wait 5 seconds before polling again\n  await new Promise(resolve => setTimeout(resolve, 5000));\n}"
          },
          {
            "lang": "Python",
            "label": "Poll for completion",
            "source": "import requests\nimport time\n\ntoken = 'YOUR_JWT_TOKEN'\nsummary_id = '123e4567-e89b-12d3-a456-426614174000'\n\n# Poll until completed\nwhile True:\n    res = requests.get(\n        f'https://api.sandbox.commure.com/ambient/scribe/v1/summaries/{summary_id}',\n        headers={'Authorization': f'Bearer {token}', 'auth-scheme': 'cognito'}\n    )\n    \n    summary = res.json()\n    print(f\"Status: {summary['status']}\")\n    \n    if summary['status'] == 'COMPLETED':\n        print(f\"Summary text: {summary['ai_task']['note_text']}\")\n        if summary['citations']:\n            print(f\"Citations: {summary['citations']['note_text']}\")\n        break\n    elif summary['status'] == 'ERROR':\n        print(f\"Error: {summary['error_message']}\")\n        break\n    \n    # Wait 5 seconds before polling again\n    time.sleep(5)"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT token obtained from /v1/auth/token endpoint. Note: All requests automatically include 'auth-scheme: cognito' header."
      }
    },
    "parameters": {
      "authSchemeHeader": {
        "name": "auth-scheme",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "enum": ["cognito"],
          "default": "cognito"
        },
        "description": "Authentication scheme",
        "example": "cognito"
      }
    },
    "schemas": {
      "TranscriptionResponse": {
        "type": "object",
        "description": "Response after submitting a transcription",
        "properties": {
          "transcription_id": {
            "type": "string",
            "format": "uuid",
            "description": "The transcription record ID"
          },
          "submitted_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when transcription was submitted"
          }
        },
        "required": ["transcription_id", "submitted_at"]
      },
      "TranscriptionStatusResponse": {
        "type": "object",
        "description": "Transcription status and results",
        "properties": {
          "transcription_id": {
            "type": "string",
            "format": "uuid",
            "description": "The transcription record ID"
          },
          "workflow_id": {
            "type": "string",
            "format": "uuid",
            "description": "The workflow ID"
          },
          "status": {
            "type": "string",
            "enum": [
              "DETECTED_FILE",
              "STT_PROCESSING",
              "STT_COMPLETED",
              "STT_ERROR",
              "STT_INCOMPLETE"
            ],
            "description": "Current transcription status"
          },
          "raw_text": {
            "type": "string",
            "nullable": true,
            "description": "Transcription text if available"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When transcription was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When transcription was last updated"
          }
        },
        "required": ["transcription_id", "workflow_id", "status", "created_at", "updated_at"]
      },
      "TemplateContentSchema": {
        "type": "object",
        "description": "JSON Schema structure for template content",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["object"],
            "description": "Must be 'object'"
          },
          "required": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Array of required field names"
          },
          "properties": {
            "type": "object",
            "description": "Object mapping field names to their property definitions",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Field type (e.g., 'string', 'number', 'boolean', 'array', 'object')"
                },
                "title": {
                  "type": "string",
                  "description": "Display title for the field"
                },
                "description": {
                  "type": "string",
                  "description": "Description/instructions for the field"
                }
              },
              "required": ["type"]
            }
          }
        },
        "required": ["type", "properties"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        },
        "required": ["detail"]
      },
      "CorrectionResponse": {
        "type": "object",
        "description": "Response object for a correction entry",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the correction"
          },
          "misspelled_text": {
            "type": "string",
            "description": "The misspelled or incorrect text"
          },
          "correct_text": {
            "type": "string",
            "description": "The correct text"
          },
          "correction_type": {
            "type": "string",
            "enum": ["PRESCRIPTION", "DISEASE", "MEDICAL_EQUIPMENT", "MEDICAL_PROCEDURE", "MEDICAL_CONDITION", "OTHER", "ACRONYM"],
            "description": "Type of correction"
          },
          "is_user_specific": {
            "type": "boolean",
            "description": "Whether this correction is user-specific (true) or global (false)"
          },
          "occurrence_count": {
            "type": "integer",
            "description": "Number of times the misspelled text has been encountered"
          },
          "correction_count": {
            "type": "integer",
            "description": "Number of times this correction has been applied"
          },
          "active": {
            "type": "boolean",
            "description": "Whether this correction is currently active"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the correction was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the correction was last updated"
          }
        },
        "required": ["id", "misspelled_text", "correct_text", "correction_type", "is_user_specific", "occurrence_count", "correction_count", "active", "created_at", "updated_at"]
      }
    }
  },
  "tags": [
    {
      "name": "auth",
      "description": "Authentication endpoints for obtaining JWT tokens"
    },
    {
      "name": "transcription",
      "description": "Audio transcription endpoints. Submit audio files for speech-to-text processing and retrieve transcription results. The transcription process is asynchronous - submit a file to receive a transcription ID, then poll the status endpoint to check progress and retrieve results."
    },
    {
      "name": "templates",
      "description": "Template management endpoints for defining clinical note structures. Templates use JSON Schema to define the fields and structure of generated notes."
    },
    {
      "name": "scribe",
      "description": "Scribe workflow endpoints for generating clinical notes from audio files or transcripts. Submit workflows with templates to generate structured clinical documentation."
    },
    {
      "name": "regenerate",
      "description": "Endpoints for regenerating scribe workflows with additional context or new audio files. Regenerate clinical notes by providing new transcripts or re-transcribing audio without creating a new scribe workflow."
    },
    {
      "name": "Chunking",
      "description": "Chunked file upload endpoints for uploading large audio files in multiple parts. Create an upload session, upload chunks in any order (including sequential or parallel uploads), and complete the session to process the uploaded audio chunks for transcription."
    },
    {
      "name": "corrections",
      "description": "Correction management endpoints for creating and managing spell corrections. Corrections map misspelled or incorrect text to the correct form and can be user-specific or global to improve transcription accuracy."
    }
  ],
  "security": [{ "bearerAuth": [] }]
}