{ "openapi": "3.0.1", "info": { "title": "Suki Developer Platform", "description": "REST and WebSocket APIs for the Suki Developer Platform. Authenticate with Login or Register to obtain a Suki access token, then integrate ambient clinical documentation, form filling, transcription, and reference metadata endpoints.", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://sdp.suki.ai", "description": "Production base URL for Suki Developer Platform REST APIs. WebSocket endpoints use the same host with `wss://`." } ], "paths": { "/api/auth/.well-known/jwks-pub.json": { "get": { "tags": [ "/api/auth" ], "summary": "Get JWKS public keys", "description": "Returns the JSON Web Key Set (JWKS) with public keys Suki uses to verify partner tokens. Use this endpoint when configuring JWT signature validation for your identity provider.", "responses": { "200": { "description": "JWKS document with public keys for partner token verification.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.PublicKeyData" } } } } }, "parameters": [], "security": [] } }, "/api/v1/ambient/content/{ambient_session_id}": { "get": { "tags": [ "/api/v1/ambient" ], "summary": "Get ambient session content (deprecated)", "description": "Returns generated clinical content for an ambient session. **Deprecated.** Use `GET /api/v1/ambient/session/{ambient_session_id}/content` instead.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ContentResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "deprecated": true, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/content/ \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/encounter/{encounter_id}/content": { "get": { "tags": [ "/api/v1/ambient/encounter" ], "summary": "Get encounter content", "description": "Returns cumulative clinical content across all ambient sessions linked to the encounter. Use the `encounter_id` from session create when you grouped multiple sessions under one visit.", "parameters": [ { "name": "encounter_id", "in": "path", "description": "UUID for the patient encounter (visit). Use the `encounter_id` from session create or the UUID you assigned when grouping multiple sessions under one visit.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.EncounterContentResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/encounter//content \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/encounter/{encounter_id}/structured-data": { "get": { "tags": [ "/api/v1/ambient/encounter" ], "summary": "Get encounter structured data", "description": "Returns structured clinical data aggregated across all ambient sessions for the encounter. Use the `encounter_id` from session create.", "parameters": [ { "name": "encounter_id", "in": "path", "description": "UUID for the patient encounter (visit). Use the `encounter_id` from session create or the UUID you assigned when grouping multiple sessions under one visit.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.EncounterStructuredDataResponse" }, "example": { "structured_data": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" }, { "code": "85", "description": "CMS-HCC model category 85", "type": "HCC" } ], "diagnosis_note": "The management of essential hypertension remains unchanged from previous plans, as it was not the focus of today's visit.", "laterality_indicator": 4, "post_coord_lex_flag": 1 } ] }, "orders": { "medication_orders": { "partial_values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ], "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/encounter//structured-data \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/create": { "post": { "tags": [ "/api/v1/ambient/session" ], "summary": "Create ambient session", "description": "Creates a new ambient session for patient encounter documentation. Returns an `ambient_session_id` to use in context, streaming, status, and content APIs. Both request body fields are optional; Suki generates any values you omit.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateSessionRequest" }, "example": { "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", "encounter_id": "123dfg-456dfg-789dfg-012dfg" } } }, "required": false }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateSessionResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/ambient/session/create \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\n \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}'" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/content": { "get": { "tags": [ "/api/v1/ambient/session" ], "summary": "Get ambient session content", "description": "Returns the generated clinical note and related content for a completed or in-progress ambient session. Poll session status if content is not ready yet.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "name": "cumulative", "in": "query", "description": "Optional. When `true`, return cumulative summary and structured data up to this session. When `false` (default), return snapshot data for this session only.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.SessionContentResponse" }, "example": { "structured_data": [ { "title": "MEDICATIONS", "data": { "medication": "albuterol", "dosage": "2 puffs" } } ], "summary": [ { "content": "Asthma exacerbation", "loinc_code": "18776-5", "title": "ASSESSMENT AND PLAN" } ] } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/session//content?cumulative= \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/context": { "post": { "tags": [ "/api/v1/ambient/session" ], "summary": "Seed ambient session context", "description": "Seeds clinical context for an ambient session before or during audio capture. Send provider, patient, visit, section, diagnosis, EMR, and medication order metadata to improve note quality. Replaces the entire context when called.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.Context" }, "example": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "ATHENA" }, "orders": { "medication_orders": { "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "metadata": { "encounter_relation": "CURRENT_ENCOUNTER", "origin": "SUKI_AMBIENT" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } }, "patient": { "dob": "2000-01-01", "sex": "male" }, "provider": { "role": "ATTENDING", "specialty": "CARDIOLOGY" }, "sections": [ { "loinc": "10164-2" } ], "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" } } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": {} }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/ambient/session//context \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\n \"diagnoses\": {\n \"values\": [\n {\n \"codes\": [\n {\n \"code\": \"30422\",\n \"description\": \"Essential hypertension\",\n \"type\": \"IMO\"\n }\n ],\n \"diagnosis_note\": \"Hypertension\"\n }\n ]\n },\n \"emr\": {\n \"target_emr\": \"ATHENA\"\n },\n \"orders\": {\n \"medication_orders\": {\n \"values\": [\n {\n \"dosage\": {\n \"quantity\": 1,\n \"raw_value\": \"1 tablet\",\n \"unit\": \"TAB\"\n },\n \"drug_name\": \"Acetaminophen 500mg Tab\",\n \"duration_in_days\": 7,\n \"end_date\": \"2026-01-08T00:00:00Z\",\n \"format\": {\n \"raw_value\": \"Tablet\"\n },\n \"frequency\": {\n \"raw_value\": \"once daily\",\n \"structured_value\": \"ONE_A_DAY\"\n },\n \"instructions\": \"Take with food\",\n \"linked_diagnosis_codes\": [\n {\n \"code\": \"I10\",\n \"type\": \"ICD10\"\n }\n ],\n \"medication_code\": {\n \"code\": \"860975\",\n \"type\": \"RXCUI\"\n },\n \"medication_timing\": {\n \"raw_value\": \"morning\",\n \"structured_value\": \"IN_THE_MORNING\"\n },\n \"metadata\": {\n \"encounter_relation\": \"CURRENT_ENCOUNTER\",\n \"origin\": \"SUKI_AMBIENT\"\n },\n \"number_of_refills\": 3,\n \"quantity_dispensed\": \"1 box\",\n \"route\": {\n \"raw_value\": \"Oral\"\n },\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"status\": \"ACTIVE\",\n \"strength\": {\n \"raw_value\": \"500mg\"\n }\n }\n ]\n }\n },\n \"patient\": {\n \"dob\": \"2000-01-01\",\n \"sex\": \"male\"\n },\n \"provider\": {\n \"role\": \"ATTENDING\",\n \"specialty\": \"CARDIOLOGY\"\n },\n \"sections\": [\n {\n \"loinc\": \"10164-2\"\n }\n ],\n \"visit\": {\n \"chief_complaint\": \"Headache\",\n \"encounter_type\": \"AMBULATORY\",\n \"reason_for_visit\": \"Follow-up for migraines\",\n \"visit_type\": \"ESTABLISHED_PATIENT\"\n }\n}'" } ], "security": [ { "SukiTokenAuth": [] } ] }, "patch": { "tags": [ "/api/v1/ambient/session" ], "summary": "Update ambient session context", "description": "Partially updates ambient session context using a field mask. Send only the context fields you want to add or change before you end the session.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.UpdateContextRequest" }, "example": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "ATHENA" }, "orders": { "medication_orders": { "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "metadata": { "encounter_relation": "CURRENT_ENCOUNTER", "origin": "SUKI_AMBIENT" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } }, "patient": { "dob": "2000-01-01", "sex": "male" }, "provider": { "role": "ATTENDING", "specialty": "CARDIOLOGY" }, "sections": [ { "loinc": "10164-2" } ], "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" } } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.UpdateContextResponse" }, "example": { "context": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "ATHENA" }, "orders": { "medication_orders": { "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "metadata": { "encounter_relation": "CURRENT_ENCOUNTER", "origin": "SUKI_AMBIENT" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } }, "patient": { "dob": "2000-01-01", "sex": "male" }, "provider": { "role": "ATTENDING", "specialty": "CARDIOLOGY" }, "sections": [ { "loinc": "10164-2" } ], "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url https://sdp.suki.ai/api/v1/ambient/session//context \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\n \"diagnoses\": {\n \"values\": [\n {\n \"codes\": [\n {\n \"code\": \"30422\",\n \"description\": \"Essential hypertension\",\n \"type\": \"IMO\"\n }\n ],\n \"diagnosis_note\": \"Hypertension\"\n }\n ]\n },\n \"emr\": {\n \"target_emr\": \"ATHENA\"\n },\n \"orders\": {\n \"medication_orders\": {\n \"values\": [\n {\n \"dosage\": {\n \"quantity\": 1,\n \"raw_value\": \"1 tablet\",\n \"unit\": \"TAB\"\n },\n \"drug_name\": \"Acetaminophen 500mg Tab\",\n \"duration_in_days\": 7,\n \"end_date\": \"2026-01-08T00:00:00Z\",\n \"format\": {\n \"raw_value\": \"Tablet\"\n },\n \"frequency\": {\n \"raw_value\": \"once daily\",\n \"structured_value\": \"ONE_A_DAY\"\n },\n \"instructions\": \"Take with food\",\n \"linked_diagnosis_codes\": [\n {\n \"code\": \"I10\",\n \"type\": \"ICD10\"\n }\n ],\n \"medication_code\": {\n \"code\": \"860975\",\n \"type\": \"RXCUI\"\n },\n \"medication_timing\": {\n \"raw_value\": \"morning\",\n \"structured_value\": \"IN_THE_MORNING\"\n },\n \"metadata\": {\n \"encounter_relation\": \"CURRENT_ENCOUNTER\",\n \"origin\": \"SUKI_AMBIENT\"\n },\n \"number_of_refills\": 3,\n \"quantity_dispensed\": \"1 box\",\n \"route\": {\n \"raw_value\": \"Oral\"\n },\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"status\": \"ACTIVE\",\n \"strength\": {\n \"raw_value\": \"500mg\"\n }\n }\n ]\n }\n },\n \"patient\": {\n \"dob\": \"2000-01-01\",\n \"sex\": \"male\"\n },\n \"provider\": {\n \"role\": \"ATTENDING\",\n \"specialty\": \"CARDIOLOGY\"\n },\n \"sections\": [\n {\n \"loinc\": \"10164-2\"\n }\n ],\n \"visit\": {\n \"chief_complaint\": \"Headache\",\n \"encounter_type\": \"AMBULATORY\",\n \"reason_for_visit\": \"Follow-up for migraines\",\n \"visit_type\": \"ESTABLISHED_PATIENT\"\n }\n}'" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/end": { "post": { "tags": [ "/api/v1/ambient/session" ], "summary": "End ambient session", "description": "Ends an ambient session and triggers clinical note generation. Call this after audio streaming completes. Short or empty recordings may return a skipped status.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": {} }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/ambient/session//end \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{session_id}/{entity}/feedback": { "post": { "tags": [ "/api/v1/ambient/session/{session_id}/{entity}/feedback" ], "summary": "Submit ambient session feedback", "description": "Submits quantitative and qualitative feedback on AI-generated clinical content for an ambient session. You can submit feedback once per entity type per session.", "parameters": [ { "name": "session_id", "in": "path", "description": "UUID for the ambient session you are rating. Use the same `ambient_session_id` from Create Ambient Session.", "required": true, "schema": { "type": "string" }, "example": "session_abc_123" }, { "name": "entity", "in": "path", "description": "Entity type you are rating. For ambient sessions, use `content` for generated clinical note content. You can submit feedback once per entity type per session.", "required": true, "schema": { "type": "string" }, "example": "content" }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FeedbackRequest" } } }, "required": true }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FeedbackResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized - Authentication failed or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden - Access denied to the requested resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "security": [ { "SukiTokenAuth": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/ambient/session///feedback \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ] } }, "/api/v1/ambient/session/{ambient_session_id}/metadata": { "post": { "tags": [ "/api/v1/ambient/session" ], "summary": "Seed ambient session metadata (deprecated)", "description": "Seeds metadata for an ambient session. **Deprecated.** Use `POST /api/v1/ambient/session/{ambient_session_id}/context` instead.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.SessionMetadata" } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": {} }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "deprecated": true, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/ambient/session//metadata \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/status": { "get": { "tags": [ "/api/v1/ambient/session" ], "summary": "Get ambient session status", "description": "Returns processing status for an ambient session, such as whether note generation is in progress, complete, or skipped.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.StatusResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/session//status \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/structured-data": { "get": { "tags": [ "/api/v1/ambient/session" ], "summary": "Get ambient session structured data", "description": "Returns structured clinical data extracted from the ambient session, including coded diagnoses and related fields when available.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.SessionStructuredDataResponse" }, "example": { "structured_data": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" }, { "code": "85", "description": "CMS-HCC model category 85", "type": "HCC" } ], "diagnosis_note": "The management of essential hypertension remains unchanged from previous plans, as it was not the focus of today's visit.", "laterality_indicator": 4, "post_coord_lex_flag": 1 } ] }, "orders": { "medication_orders": { "partial_values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ], "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/session//structured-data \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/transcript": { "get": { "tags": [ "/api/v1/ambient/session" ], "summary": "Get ambient session transcript", "description": "Returns completed transcripts for the ambient session after speech recognition finishes.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CompletedTranscriptResponse" }, "example": { "final_transcript": [ { "end_offset": { "hours": 0, "minutes": 6, "nanos": 80000000, "seconds": 42 }, "end_time": "2024-12-04T09:40:48.792948332Z", "lang_id": "en", "recording_id": "c9d59aa8-cd48-4f5a-be81-5d0c9d2a5885", "start_offset": { "hours": 0, "minutes": 6, "nanos": 80000000, "seconds": 42 }, "start_time": "2024-12-04T09:40:42.393948332Z", "transcript": "The patient has shown an allergy to pollen", "transcript_id": "01JE8GP4RTHH0KDEGRSTRVPMGH" } ] } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/session//transcript \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/ambient/session/{ambient_session_id}/recording": { "get": { "operationId": "getSessionRecording", "tags": [ "/api/v1/ambient/session" ], "summary": "Get ambient session recording URLs", "description": "Returns presigned URLs to stream or download session recordings. URLs are temporary; use them before they expire.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "UUID for the ambient session. Use the `ambient_session_id` returned from Create Ambient Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "description": "If true, returns download-only URLs; if false or omitted, URLs support streaming with Range requests.", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.SessionRecordingResponse" }, "example": { "recordings": [ { "recording_id": "01KFJZTJWZH28GRHQXVCGW4Y47", "presigned_url": "https://storage.googleapis.com/...", "expires_at": 1738765432, "sequence_number": 1 } ], "is_streamable": true } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Expired or missing token. User message returned in the response body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" }, "example": { "code": 401, "message": "Invalid authentication credentials." } } } }, "404": { "description": "Session exists, but recording audio is missing or not yet available. User message returned in the response body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" }, "example": { "code": 404, "message": "Recording not found or decryption in progress." } } } }, "410": { "description": "Session is past the recording retention period (7 days). User message returned in the response body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" }, "example": { "code": 410, "message": "Recording has expired per retention policy." } } } }, "500": { "description": "Service failure. User message returned in the response body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" }, "example": { "code": 500, "message": "An internal error occurred." } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/ambient/session//recording?download= \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/auth/login": { "post": { "tags": [ "/api/v1/auth" ], "summary": "Login", "description": "Authenticates a registered provider and returns a Suki access token (`suki_token`). Use that token as `sdp_suki_token` on all subsequent API calls. Tokens expire after one hour.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationRequest" } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "parameters": [], "security": [] } }, "/api/v1/auth/register": { "post": { "tags": [ "/api/v1/auth" ], "summary": "Register provider", "description": "Registers a new provider in Suki or links an existing provider to your partner organization. This is a one-time setup call per provider.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.RegistrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Resource created successfully.", "content": {} }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ConflictError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "parameters": [], "security": [] } }, "/api/v1/info": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get system information", "description": "Returns reference metadata Suki supports for ambient integrations, including LOINC codes, specialties, diagnosis code types, encounter types, visit types, provider roles, and medication order enums.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.GetInfoResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/diagnosis": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported diagnosis code types", "description": "Returns diagnosis code types Suki accepts in session context, such as ICD10 and IMO.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.DiagnosisCodesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/diagnosis \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/loincs": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported LOINC codes", "description": "Returns LOINC codes for clinical note sections Suki can generate. Use these codes in the `sections` field when seeding or updating session context.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.LoincCodesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/loincs \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/specialties": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported specialties", "description": "Returns medical specialties Suki recognizes in provider context.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.SpecialtyCodesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/specialties \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/encounter-types": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported encounter types", "description": "Returns encounter type values you can send in visit context, such as AMBULATORY, INPATIENT, and EMERGENCY.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.EncounterTypesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/encounter-types \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/visit-types": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported visit types", "description": "Returns visit type values you can send in visit context.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.VisitTypesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/visit-types \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/provider-roles": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get supported provider roles", "description": "Returns provider role values you can send in provider context.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ProviderRolesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/provider-roles \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/user/preferences": { "patch": { "tags": [ "/api/v1/user/preferences" ], "summary": "Update user preferences", "description": "Updates personalization preferences for the authenticated user, such as note verbosity and section format. Settings apply to future sessions for that user. Send only the fields you want to change.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.Preference" } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.UpdateUserPreferencesResponse" }, "example": { "preference": { "personalization_preference": { "section_format": [ { "loinc": "10164-2", "style": "NARRATIVE" } ], "verbosity": "CONCISE" } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url https://sdp.suki.ai/api/v1/user/preferences \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/transcription/session/create": { "post": { "tags": [ "/api/v1/transcription/session" ], "summary": "Create transcription session", "description": "Creates a transcription session for real-time speech-to-text over WebSocket. Returns a `transcription_session_id` to use when connecting to `/ws/transcribe`.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateTranscriptionSessionRequest" } } }, "required": false }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateTranscriptionSessionResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "body", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/transcription/session/create \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/ws/transcribe": { "get": { "tags": [ "/ws" ], "summary": "Stream audio for transcription", "description": "Opens a WebSocket to stream audio for real-time transcription. Browser clients authenticate with the `Sec-WebSocket-Protocol` header; non-browser clients send `sdp_suki_token` and `transcription_session_id` as HTTP headers on the upgrade request.", "parameters": [ { "name": "Sec-WebSocket-Protocol", "in": "header", "description": "Required FOR BROWSER CLIENTS ONLY. Sent during WebSocket handshake. Browsers must use the same subprotocol the grpc-wsproxy maps to Authorization: 'SukiAmbientAuth,,' (comma-separated; token second, transcription session id third). Other names (e.g. SukiTranscriptionAuth) are not mapped and typically yield 401.", "schema": { "type": "string" } }, { "name": "transcription_session_id", "in": "header", "description": "Required for non-browser clients only. UUID from Create Transcription Session.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "101": { "description": "Switching Protocols - Indicates successful WebSocket handshake.", "content": { "application/json": { "schema": { "type": "string" } } } }, "200": { "description": "OK - May indicate successful stream processing or completion (e.g., sending 'EOF' message). Specific meaning depends on implementation after handshake.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request - Invalid parameters, headers, or request format.", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - Authentication failed (invalid token/session, incorrect protocol/headers).", "content": { "application/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Client is authenticated but not authorized for this action.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Internal Server Error - Abnormal closure or server-side issue.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/ws/transcribe \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --header 'transcription_session_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/transcription/session/{transcription_session_id}/end": { "post": { "tags": [ "/api/v1/transcription/session" ], "summary": "End transcription session", "description": "Ends a transcription session after you finish streaming audio on `/ws/transcribe`.", "parameters": [ { "name": "transcription_session_id", "in": "path", "description": "UUID for the transcription session. Use the `transcription_session_id` returned from Create Transcription Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "invalid request" } } } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "invalid token" } } } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "forbidden" } } } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "not found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "internal server error" } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/transcription/session//end \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/webhooks/notification": { "post": { "tags": [ "/webhooks" ], "summary": "Receive asynchronous notifications (partner webhook)", "description": "Specification for the webhook endpoint your application hosts to receive asynchronous notifications from Suki when ambient session processing completes or fails. Suki sends POST requests to your configured notification URL.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FailureNotification" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": {} }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codegen-request-body-name": "failure", "parameters": [], "security": [] } }, "/ws/stream": { "get": { "tags": [ "/ws" ], "summary": "Stream ambient audio", "description": "Opens a WebSocket to stream audio for ambient or form-filling sessions. Create the session and seed context before connecting. Browser clients authenticate with `Sec-WebSocket-Protocol`; non-browser clients send `sdp_suki_token`, optional `sdp_provider_id`, and `ambient_session_id` as headers.", "parameters": [ { "name": "Sec-WebSocket-Protocol", "in": "header", "description": "Required FOR BROWSER CLIENTS ONLY. Sent during WebSocket handshake. Format: 'SukiAmbientAuth,,' (comma-separated, no spaces required between parts).", "schema": { "type": "string" } }, { "name": "ambient_session_id", "in": "header", "description": "Required for non-browser clients only. Session UUID from Create Ambient Session or Create Form Filling Session.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "101": { "description": "Switching Protocols - Indicates successful WebSocket handshake.", "content": { "application/json": { "schema": { "type": "string" } } } }, "200": { "description": "OK - May indicate successful stream processing or completion (e.g., sending 'EOF' message). Specific meaning depends on implementation after handshake.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request - Invalid parameters, headers, or request format.", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - Authentication failed (invalid token/session, incorrect protocol/headers).", "content": { "application/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Client is authenticated but not authorized for this action.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Internal Server Error - Abnormal closure or server-side issue.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/ws/stream \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --header 'ambient_session_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication order metadata", "description": "Returns all supported medication order reference lists in one response.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AllOrderInfoResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/coding-systems": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication coding systems", "description": "Returns medication coding systems you can use in medication order context, such as RXCUI.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.MedicationCodingSystemsResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/coding-systems \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/dosage-units": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication dosage units", "description": "Returns supported dosage unit values for medication orders.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.MedicationDosageUnitsResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/dosage-units \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/encounter-relations": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get order encounter relations", "description": "Returns supported encounter relation values for medication order metadata.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.OrderEncounterRelationsResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/encounter-relations \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/frequencies": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication frequency types", "description": "Returns supported structured frequency values for medication orders.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.MedicationFrequencyTypesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/frequencies \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/medication-timings": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication timings", "description": "Returns supported medication timing values for medication orders.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.MedicationTimingsResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/medication-timings \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/origins": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get order origins", "description": "Returns supported origin values for medication order metadata.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.OrderOriginsResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/origins \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/orders/statuses": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get medication order statuses", "description": "Returns supported status values for medication orders.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.MedicationOrderStatusesResponse" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/orders/statuses \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/create": { "post": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Create form-filling session", "description": "Creates a form-filling session for structured medical form capture. Returns a session ID in the `ambient_session_id` response field. That ID identifies the form-filling session for context, streaming, status, structured-data, and feedback APIs. It is not an ambient clinical documentation session ID.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateFormFillingSessionRequest" }, "example": {} } } }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateFormFillingSessionResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/form-filling/session/create \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{}'" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/{ambient_session_id}/context": { "post": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Seed form-filling session context", "description": "Seeds form template metadata for a form-filling session before audio capture. Include `form_filling.values` with a `form_template_id` for each template.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingSessionContext" } } }, "required": false }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "default": { "summary": "Success", "value": {} } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/form-filling/session//context \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] }, "patch": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Update form-filling session context", "description": "Partially updates form-filling session context. On success, returns the updated `context.form_filling` value.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingUpdateContextRequest" } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingUpdateContextResponse" }, "example": { "context": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url https://sdp.suki.ai/api/v1/form-filling/session//context \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/{ambient_session_id}/end": { "post": { "tags": [ "/api/v1/form-filling/session" ], "summary": "End form-filling session", "description": "Ends a form-filling session and triggers structured form output generation.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "default": { "summary": "Success", "value": {} } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/form-filling/session//end \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/{ambient_session_id}/status": { "get": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Get form-filling session status", "description": "Returns processing status for a form-filling session.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingStatusResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/form-filling/session//status \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/{ambient_session_id}/structured-data": { "get": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Get form-filling structured data", "description": "Returns structured medical form output for a completed form-filling session.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingStructuredDataResponse" }, "example": { "structured_data": { "generated_values": [ { "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "data": { "additionalProp1": {} }, "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template", "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "metadata": { "additionalProp1": {} }, "patient_id": "patient-123", "status": "MEDICAL_FORM_STATUS_COMPLETED", "title": "Adult Vitals", "type": "VITALS_ASSESSMENT" } ], "non_generated_values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/form-filling/session//structured-data \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/form-filling/session/{ambient_session_id}/{entity}/feedback": { "post": { "tags": [ "/api/v1/form-filling/session" ], "summary": "Submit form-filling session feedback", "description": "Submits feedback on form-filling session output. You can submit feedback once per entity type per session.", "parameters": [ { "name": "ambient_session_id", "in": "path", "description": "Form-filling session ID. The path parameter is named `ambient_session_id`, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form Filling Session, or the UUID you supplied in that request.", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "path", "description": "Entity type you are rating. For form-filling sessions, use `AMBIENT_GENERATED_MEDICAL_FORM` for generated medical form output.", "required": true, "schema": { "type": "string", "example": "AMBIENT_GENERATED_MEDICAL_FORM" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingFeedbackPayload" }, "example": { "feedback": { "qualitative_comments": "Accurate and well-structured form output.", "ratingFeedback": { "min_rating": 1, "max_rating": 5, "rating": 5 } }, "feedback_metadata": { "form_id": "018f94e8-7aa8-7bfd-bc83-046262001234" } } } }, "required": true }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.SubmitFeedbackResponse" } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The session, encounter, or resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/form-filling/session///feedback \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\n \"feedback\": {\n \"qualitative_comments\": \"Accurate and well-structured form output.\",\n \"ratingFeedback\": {\n \"min_rating\": 1,\n \"max_rating\": 5,\n \"rating\": 5\n }\n },\n \"feedback_metadata\": {\n \"form_id\": \"018f94e8-7aa8-7bfd-bc83-046262001234\"\n }\n}'" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/info/suki-medical-form-templates": { "get": { "tags": [ "/api/v1/info" ], "summary": "Get Suki medical form templates", "description": "Returns Suki-defined medical form templates. Use each template's `template_id` as `form_template_id` when seeding or updating form-filling session context.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.GetSukiFormTemplatesResponse" }, "example": { "form_templates": [ { "description": "Standard vitals collection template for adult patients.", "name": "Adult Vitals", "template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "type": "VITALS_ASSESSMENT", "schema": { "items": [ { "code": "Q003", "id": "respiratory_pattern", "kind": "field", "options": [ { "code": null, "display": "Regular" }, { "code": null, "display": "Shallow" } ], "pattern": "", "question": "Respiratory Pattern / Effort", "type": "radio" } ] } } ] } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. The authenticated user cannot access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url https://sdp.suki.ai/api/v1/info/suki-medical-form-templates \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } } }, "components": { "schemas": { "controllers.AuthenticationError": { "type": "object", "properties": { "code": { "type": "integer", "example": 401, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "invalid token", "description": "Human-readable description of the authentication failure." } }, "description": "Error response when authentication fails." }, "controllers.AuthenticationRequest": { "type": "object", "required": [ "partner_id", "partner_token" ], "properties": { "partner_id": { "type": "string", "description": "Unique identifier for the partner. This will be shared securely by Suki to the partner through a separate partner registration process.", "example": "your-partner-id" }, "partner_token": { "type": "string", "description": "JWT token issued by trusted authorization server. The token must include Provider Email.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "provider_id": { "type": "string", "description": "**Optional** - Unique identifier for the provider. This is required for Bearer type partners only and will be ignored for other partner types. This must match a pre-defined expression.", "example": "provider-123" } }, "description": "Partner credentials from onboarding. Bearer partners must also include `provider_id`.", "example": { "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id": "provider-123" } }, "controllers.AuthenticationResponse": { "type": "object", "properties": { "suki_token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "description": "JWT access token for the authenticated provider. Pass this value as `sdp_suki_token` on subsequent requests. Expires after one hour." } }, "description": "Suki access token returned after successful Login." }, "controllers.BadRequestError": { "type": "object", "properties": { "code": { "type": "integer", "example": 400, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "invalid request", "description": "Human-readable description of the validation or request error." } }, "description": "Error response when the request fails validation." }, "controllers.Code": { "type": "object", "properties": { "code": { "type": "string", "description": "Code value for the diagnosis or medication coding system.", "example": "30422" }, "description": { "type": "string", "description": "Description of the code. For HCC codes, the description uses the format `CMS-HCC model category `.", "example": "Essential hypertension" }, "type": { "type": "string", "description": "Diagnosis coding system for this code value. HCC codes are returned in ambient structured data output when the ICD-10-CM diagnosis maps to a CMS-HCC model category (V28).", "example": "IMO", "enum": [ "UNSPECIFIED", "IMO", "ICD10", "SNOMED", "HCC" ] } } }, "controllers.CompletedTranscript": { "type": "object", "properties": { "end_offset": { "type": "object", "description": "Ending time of each transcript segment relative to the beginning of the audio or context in which it appears.", "allOf": [ { "$ref": "#/components/schemas/controllers.Offset" } ] }, "end_time": { "type": "string", "description": "End Time of the transcript.", "example": "2024-12-04T09:40:48.792948332Z" }, "lang_id": { "type": "string", "description": "Language identifier for the transcript content", "example": "en" }, "recording_id": { "type": "string", "description": "Recording ID associated with the transcript.", "example": "c9d59aa8-cd48-4f5a-be81-5d0c9d2a5885" }, "start_offset": { "type": "object", "description": "Starting time of each transcript segment relative to the beginning of the audio or context in which it appears.", "allOf": [ { "$ref": "#/components/schemas/controllers.Offset" } ] }, "start_time": { "type": "string", "description": "Start Time of the transcript.", "example": "2024-12-04T09:40:42.393948332Z" }, "transcript": { "type": "string", "description": "Transcript for an audio chunk.", "example": "The patient has shown an allergy to pollen" }, "transcript_id": { "type": "string", "description": "Sortable ULID for each transcript.", "example": "01JE8GP4RTHH0KDEGRSTRVPMGH" } }, "description": "Transcript for an audio chunk" }, "controllers.CompletedTranscriptResponse": { "type": "object", "properties": { "final_transcript": { "type": "array", "description": "Collection of transcripts for the ambient session", "items": { "$ref": "#/components/schemas/controllers.CompletedTranscript" } } }, "description": "Response body for the /session/{ambient_session_id}/transcript endpoint" }, "controllers.ConflictError": { "type": "object", "properties": { "code": { "type": "integer", "example": 409, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "conflict", "description": "Human-readable description of the conflict." } }, "description": "Conflict Response" }, "controllers.Content": { "type": "object", "properties": { "content": { "type": "string", "example": "Asthma exacerbation", "description": "Generated text for the clinical note section." }, "loinc_code": { "type": "string", "example": "18776-5", "description": "LOINC code that identifies the note section." }, "title": { "type": "string", "example": "ASSESSMENT AND PLAN", "description": "Section title, such as ASSESSMENT AND PLAN." } }, "description": "Generated content for the session" }, "controllers.ContentBlock": { "type": "object", "properties": { "content": { "type": "string", "description": "The body of the content block usually refers to the content of the section.", "example": "Asthma exacerbation" }, "loinc_code": { "type": "string", "description": "The LOINC code of the content block.", "example": "18776-5" }, "title": { "type": "string", "description": "The title of the content block usually refers to section name.", "example": "ASSESSMENT AND PLAN" } } }, "controllers.ContentResponse": { "type": "object", "properties": { "contents": { "type": "array", "description": "Content for the ambient session", "items": { "$ref": "#/components/schemas/controllers.Content" } } }, "description": "Generated clinical note sections for the ambient session." }, "controllers.Context": { "type": "object", "properties": { "diagnoses": { "type": "object", "description": "**Optional** - Existing diagnoses and coded values to include in note generation.", "allOf": [ { "$ref": "#/components/schemas/controllers.DiagnosesContext" } ] }, "emr": { "type": "object", "description": "**Optional** - EMR context, including the target EMR system.", "allOf": [ { "$ref": "#/components/schemas/controllers.EmrContext" } ] }, "orders": { "type": "object", "description": "**Optional** - Medication orders and related order context.", "allOf": [ { "$ref": "#/components/schemas/controllers.OrdersContext" } ] }, "patient": { "type": "object", "description": "**Optional** - Patient demographics such as date of birth and sex.", "allOf": [ { "$ref": "#/components/schemas/controllers.PatientContext" } ] }, "provider": { "type": "object", "description": "**Optional** - Provider role and specialty for the session.", "allOf": [ { "$ref": "#/components/schemas/controllers.ProviderContext" } ] }, "sections": { "type": "array", "description": "**Optional** - Information about the sections to be generated.\nIf not provided, all supported [note-sections](/documentation/note-sections) will be generated.", "items": { "$ref": "#/components/schemas/controllers.SectionContext" } }, "visit": { "type": "object", "description": "**Optional** - Visit details such as chief complaint and encounter type.", "allOf": [ { "$ref": "#/components/schemas/controllers.VisitContext" } ] } }, "description": "Clinical context for the ambient session, including provider, patient, visit, sections, diagnoses, EMR, and medication orders." }, "controllers.CreateSessionRequest": { "type": "object", "properties": { "ambient_session_id": { "type": "string", "description": "**Optional** - UUID for this ambient session. Suki generates one when omitted and returns it in the response.", "example": "123dfg-456dfg-789dfg-012dfg" }, "encounter_id": { "type": "string", "description": "**Optional** - UUID for the patient encounter. Reuse the same value across multiple session create calls to group sessions under one visit. Suki generates one when omitted.", "example": "123dfg-456dfg-789dfg-012dfg" }, "multilingual": { "type": "boolean", "description": "**Deprecated.** Multilingual support is now true by default. To disable it, contact the Suki support team.", "example": true, "deprecated": true } }, "description": "Optional session identifiers. Suki generates `ambient_session_id` and `encounter_id` when omitted." }, "controllers.CreateSessionResponse": { "type": "object", "properties": { "ambient_session_id": { "type": "string", "example": "123dfg-456dfg-789dfg-012dfg", "description": "UUID for the created ambient session. Store this for later API calls." } }, "description": "New ambient session identifiers returned after create." }, "controllers.CreateTranscriptionSessionRequest": { "type": "object", "properties": { "audio_config": { "type": "object", "description": "**Optional** - Audio configuration for the transcription session", "allOf": [ { "$ref": "#/components/schemas/controllers.TranscriptionAudioConfig" } ] }, "transcription_session_id": { "type": "string", "description": "**Optional** - UUID format. If not provided, a session ID will be automatically generated.", "example": "123dfg-456dfg-789dfg-012dfg" } }, "description": "Optional transcription session ID and audio configuration. Suki generates an ID when omitted.", "example": { "audio_config": { "audio_encoding": "LINEAR16", "audio_language": "en-US", "sample_rate_hertz": 16000 }, "transcription_session_id": "123dfg-456dfg-789dfg-012dfg" } }, "controllers.CreateTranscriptionSessionResponse": { "type": "object", "properties": { "transcription_session_id": { "type": "string", "description": "Unique identifier for the transcription session", "example": "123dfg-456dfg-789dfg-012dfg" } }, "description": "Response body for the /transcription/session/create endpoint", "example": { "transcription_session_id": "123dfg-456dfg-789dfg-012dfg" } }, "controllers.TranscriptionAudioConfig": { "type": "object", "properties": { "audio_encoding": { "type": "string", "description": "**Optional** - Audio encoding format", "example": "LINEAR16", "enum": [ "LINEAR16" ] }, "audio_language": { "type": "string", "description": "**Optional** - Language code for audio transcription", "example": "en-US" }, "sample_rate_hertz": { "type": "integer", "description": "**Optional** - Sample rate in Hertz", "example": 16000 } }, "description": "Audio configuration for transcription" }, "controllers.TranscriptionWsSpeaker": { "type": "object", "properties": { "id": { "type": "string", "description": "Speaker identifier for diarization", "example": "S1" } } }, "controllers.TranscriptionWsWord": { "type": "object", "properties": { "word": { "type": "string", "description": "Recognized word", "example": "patient" }, "speaker": { "$ref": "#/components/schemas/controllers.TranscriptionWsSpeaker" } } }, "controllers.TranscriptionWsTranscript": { "type": "object", "properties": { "transcript": { "type": "string", "description": "Recognized text for this frame, or **EOF** on the terminal end-of-stream frame", "example": "The patient reports feeling better today" }, "words": { "type": "array", "description": "Word-level detail with optional speaker IDs. Typically populated on **is_final: true** frames; partial frames often send an empty array.", "items": { "$ref": "#/components/schemas/controllers.TranscriptionWsWord" } } } }, "controllers.TranscriptionStreamResponse": { "type": "object", "properties": { "transcript": { "$ref": "#/components/schemas/controllers.TranscriptionWsTranscript" }, "is_final": { "type": "boolean", "description": "**false** = partial (interim) transcript that may change; **true** = final segment the recognizer will not revise", "example": false }, "transcript_id": { "type": "string", "description": "Sortable ULID generated per inbound frame (including partials). Do not use as a deduplication key for the same utterance.", "example": "01J9XABCDEFGHJKMNPQRSTVWXYZ" } }, "description": "Inbound JSON text frame on GET /ws/transcribe (one object per WebSocket message). Empty transcript text is not sent except for the terminal EOF frame.", "example": { "transcript": { "transcript": "the recognized text so far", "words": [] }, "is_final": false, "transcript_id": "01J9XABCDEFGHJKMNPQRSTVWXYZ" } }, "controllers.EndTranscriptionSessionResponse": { "type": "object", "properties": { "transcription_session_id": { "type": "string", "description": "Unique identifier for the transcription session", "example": "123dfg-456dfg-789dfg-012dfg" }, "status": { "type": "string", "description": "Final status of the transcription session", "example": "completed", "enum": [ "completed", "cancelled", "failed" ] }, "final_transcript": { "type": "string", "description": "Complete transcript of the entire session", "example": "The patient reports feeling better today. Blood pressure is stable at 120/80." }, "duration": { "type": "integer", "description": "Total duration of the session in seconds", "example": 300 }, "ended_at": { "type": "string", "description": "Timestamp when the session was ended", "example": "2024-11-26T10:35:00Z" } }, "description": "Response body for the /transcription/session/{transcription_session_id}/end endpoint" }, "controllers.Diagnoses": { "type": "object", "properties": { "values": { "type": "array", "description": "list of diagnoses", "items": { "$ref": "#/components/schemas/controllers.DiagnosisResponse" } } } }, "controllers.DiagnosesContext": { "type": "object", "properties": { "values": { "type": "array", "description": "**Optional** - Array of diagnosis requests", "items": { "$ref": "#/components/schemas/controllers.DiagnosisRequest" } } } }, "controllers.DiagnosisCodesResponse": { "type": "object", "properties": { "diagnosis_code_types": { "type": "array", "description": "Information about supported diagnosis code types", "items": { "$ref": "#/components/schemas/controllers.DiagnosisInfo" } } }, "description": "Response body for the /info/diagnosis endpoint" }, "controllers.DiagnosisInfo": { "type": "object", "properties": { "code_type": { "type": "string", "description": "Code system (for example, \"ICD10\", \"IMO\", \"SNOMED\", \"HCC\")", "example": "ICD10" } }, "description": "Information about a diagnosis code type. HCC is returned in ambient structured data output when an ICD-10-CM diagnosis maps to a CMS-HCC model category." }, "controllers.DiagnosisRequest": { "type": "object", "properties": { "codes": { "type": "array", "description": "**Optional** - Codes associated with the diagnosis. When sending context, use ICD10 or IMO. HCC codes are returned in structured data output only.", "items": { "$ref": "#/components/schemas/controllers.Code" } }, "diagnosis_note": { "type": "string", "description": "**Optional** - Diagnosis note", "example": "Hypertension" } } }, "controllers.DiagnosisResponse": { "type": "object", "properties": { "codes": { "type": "array", "description": "Codes associated with the diagnosis. Structured data output includes ICD10, IMO, SNOMED (when available), and HCC. HCC values are derived from the ICD-10-CM code using the CMS-HCC V28 model.", "items": { "$ref": "#/components/schemas/controllers.Code" } }, "diagnosis_note": { "type": "string", "description": "Diagnosis note", "example": "The management of essential hypertension remains unchanged from previous plans, as it was not the focus of today's visit." }, "laterality_indicator": { "type": "integer", "description": "Laterality indicator", "example": 4 }, "post_coord_lex_flag": { "type": "integer", "description": "Post-coordination lexical flag", "example": 1 } } }, "controllers.Dosage": { "type": "object", "properties": { "quantity": { "type": "number", "description": "(Optional) Dosage quantity", "example": 1 }, "raw_value": { "type": "string", "description": "(Optional) Raw dosage text", "example": "1 tablet" }, "unit": { "type": "string", "description": "(Optional) Dosage unit", "example": "TAB" } } }, "controllers.EncounterContentResponse": { "type": "object", "properties": { "structured_data": { "type": "array", "description": "Structured data extracted from the encounter", "items": { "$ref": "#/components/schemas/controllers.StructuredDataBlock" } }, "summary": { "type": "array", "description": "Cumulative summary of the encounter", "items": { "$ref": "#/components/schemas/controllers.ContentBlock" } } }, "description": "Response body for the /encounter/{encounter_id}/content endpoint" }, "controllers.EncounterStructuredDataResponse": { "type": "object", "properties": { "structured_data": { "$ref": "#/components/schemas/controllers.StructuredData" } }, "description": "Response body for the /encounter/{encounter_id}/structured-data endpoint" }, "controllers.EmrContext": { "type": "object", "properties": { "target_emr": { "type": "string", "description": "**Optional** - Target EMR for context-aware processing, such as order submission and validation rules. Supported values include ATHENA, EPIC, and CERNER.", "enum": [ "ATHENA", "EPIC", "CERNER" ], "example": "ATHENA" } }, "description": "Target EMR for context-aware processing." }, "controllers.FailureNotification": { "type": "object", "properties": { "encounter_id": { "type": "string", "description": "Id of the encounter to which the payload belongs.", "example": "29de56bc-960a-4cd5-b18f-79a798d62874" }, "error_code": { "type": "string", "description": "Error code.", "example": "ERROR_CODE_TRANSCRIPTION" }, "error_detail": { "type": "string", "description": "Details of the error, if any.", "example": "Error in transcription" }, "session_id": { "type": "string", "description": "Id of the session that failed.", "example": "20965414-929a-4f71-a3e5-b92bec07d086" }, "status": { "type": "string", "example": "failure" } }, "description": "Webhook payload Suki sends when session processing fails." }, "controllers.Format": { "type": "object", "properties": { "raw_value": { "type": "string", "description": "(Optional) Raw medication form", "example": "Tablet" } } }, "controllers.Frequency": { "type": "object", "properties": { "raw_value": { "type": "string", "description": "(Optional) Raw frequency text", "example": "once daily" }, "structured_value": { "type": "string", "description": "(Optional) Frequency enum", "example": "ONE_A_DAY" } } }, "controllers.ForbiddenError": { "type": "object", "properties": { "code": { "type": "integer", "example": 403, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "forbidden", "description": "Human-readable description of the authorization failure." } }, "description": "Error response when the caller lacks permission." }, "controllers.GetInfoResponse": { "description": "Response body for the /info endpoints with flexible data based on category", "type": "object", "properties": { "diagnosis_code_types": { "description": "Information about supported diagnosis code types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.DiagnosisInfo" } }, "encounter_types": { "description": "Information about supported encounter types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.EncounterTypeInfo" } }, "loincs": { "description": "Information about supported section codes", "type": "array", "items": { "$ref": "#/components/schemas/controllers.LoincInfo" } }, "medication_coding_systems": { "description": "Information about supported medication coding systems", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationCodingSystemInfo" } }, "medication_dosage_units": { "description": "Information about supported medication dosage units", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationDosageUnitInfo" } }, "medication_frequency_types": { "description": "Information about supported medication frequency types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationFrequencyTypeInfo" } }, "medication_order_statuses": { "description": "Information about supported medication order statuses", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderStatusInfo" } }, "medication_timings": { "description": "Information about supported medication timings", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationTimingInfo" } }, "order_encounter_relations": { "description": "Information about supported order encounter relations", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderEncounterRelationInfo" } }, "order_origins": { "description": "Information about supported order origins", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderOriginInfo" } }, "provider_roles": { "description": "Information about supported provider roles", "type": "array", "items": { "$ref": "#/components/schemas/controllers.ProviderRoleInfo" } }, "specialties": { "description": "Information about supported specialties", "type": "array", "items": { "$ref": "#/components/schemas/controllers.SpecialtyInfo" } }, "visit_types": { "description": "Information about supported visit types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.VisitTypeInfo" } } } }, "controllers.InternalServerError": { "type": "object", "properties": { "code": { "type": "integer", "example": 500, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "internal server error", "description": "Human-readable description of the server error." } }, "description": "Error response when the server encounters an unexpected error." }, "controllers.KeyData": { "type": "object", "properties": { "alg": { "type": "string", "description": "The specific cryptographic algorithm used with the key.", "example": "RS256" }, "e": { "type": "string", "description": "The exponent for the RSA public key : https://tools.ietf.org/html/rfc7518#page-30", "example": "AQAB" }, "kid": { "type": "string", "description": "The unique identifier for the key.", "example": "partner-jwks-key-1" }, "kty": { "type": "string", "description": "The family of cryptographic algorithms used with the key.", "example": "RSA" }, "n": { "type": "string", "description": "The modulus for the RSA public key : https://tools.ietf.org/html/rfc7518#page-30", "example": "yeNlzlub94YgerT030codqEztjfU_S6X4DbDA_iVKkjAWtYfPHDzz_sPCT1Axz6isZdf3lHpq_gYX4Sz-cbe4rjmigxUxr-FgKHQy3HeCdK6hNq9ASQvMK9LBOpXDNn7mei6RZWom4wo3CMvvsY1w8tjtfLb-yQwJPltHxShZq5-ihC9irpLI9xEBTgG12q5lGIFPhTl_7inA1PFK97LuSLnTJzW0bj096v_TMDg7pOWm_zHtF53qbVsI0e3v5nmdKXdFf9BjIARRfVrbxVxiZHjU6zL6jY5QJdh1QCmENoejj_ytspMmGW7yMRxzUqgxcAqOBpVm0b-_mW3HoBdjQ" }, "use": { "type": "string", "description": "How the key was meant to be used; sig represents the signature.", "example": "sig" } }, "description": "Each property in the key is defined by the JWK specification https://datatracker.ietf.org/doc/html/rfc7517#section-4 or, for algorithm-specific properties, in https://tools.ietf.org/html/rfc7518" }, "controllers.LinkedDiagnosisCode": { "type": "object", "properties": { "code": { "type": "string", "description": "(*Required) Diagnosis code value", "example": "I10" }, "type": { "type": "string", "description": "(*Required) Diagnosis coding system", "example": "ICD10" } } }, "controllers.Link": { "type": "object", "properties": { "href": { "type": "string", "example": "/path/to/resource", "description": "URL path or absolute URL for the linked resource." }, "method": { "type": "string", "example": "GET", "description": "HTTP method to call the linked resource." }, "name": { "type": "string", "example": "name", "description": "Human-readable label for the link target." }, "type": { "type": "string", "example": "application/json", "description": "Expected response content type for the link." } } }, "controllers.Links": { "type": "object", "properties": { "contents": { "type": "array", "description": "Links to non-cumulative content for each session so far for the encounter.", "items": { "$ref": "#/components/schemas/controllers.Link" } }, "encounter_content": { "type": "array", "description": "Link to cumulative content for the encounter.", "items": { "$ref": "#/components/schemas/controllers.Link" } }, "status": { "type": "array", "description": "Links to status of each session so far for the encounter.", "items": { "$ref": "#/components/schemas/controllers.Link" } }, "transcripts": { "type": "array", "description": "Links to the transcripts of each session so far for the encounter.", "items": { "$ref": "#/components/schemas/controllers.Link" } } } }, "controllers.LoincCodesResponse": { "type": "object", "properties": { "loincs": { "type": "array", "description": "Information about supported section codes", "items": { "$ref": "#/components/schemas/controllers.LoincInfo" } } }, "description": "Response body for the /info/loincs endpoint" }, "controllers.LoincInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "The LOINC code (e.g., \"10164-2\")", "example": "10164-2" }, "common_name": { "type": "string", "description": "Human-readable name for the LOINC code", "example": "History of Present Illness" } }, "description": "Information about a LOINC code" }, "controllers.NotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404, "description": "HTTP status code for the error." }, "message": { "type": "string", "example": "not found", "description": "Human-readable description of the missing resource." } }, "description": "Error response when the requested resource was not found." }, "controllers.RecordingItem": { "type": "object", "properties": { "recording_id": { "type": "string", "description": "Unique identifier for the recording.", "example": "01KFJZTJWZH28GRHQXVCGW4Y47" }, "presigned_url": { "type": "string", "description": "Temporary URL to stream or download the recording.", "example": "https://storage.googleapis.com/..." }, "expires_at": { "type": "integer", "description": "Unix timestamp when the presigned URL expires.", "example": 1738765432 }, "sequence_number": { "type": "integer", "description": "Order or part index of the recording.", "example": 1 } }, "description": "A single recording entry with presigned URL and metadata" }, "controllers.SessionRecordingResponse": { "type": "object", "properties": { "recordings": { "type": "array", "description": "List of recordings with presigned URLs for the ambient session.", "items": { "$ref": "#/components/schemas/controllers.RecordingItem" } }, "is_streamable": { "type": "boolean", "description": "Whether the returned URLs support streaming with Range requests.", "example": true } }, "description": "Response body for the /session/{ambient_session_id}/recording endpoint" }, "controllers.NoteSection": { "type": "object", "properties": { "description": { "type": "string", "example": "The main reason for the visit" }, "title": { "type": "string", "example": "CHIEF COMPLAINT" } }, "description": "Note section definition" }, "controllers.Offset": { "type": "object", "properties": { "hours": { "type": "integer", "example": 0 }, "minutes": { "type": "integer", "example": 6 }, "nanos": { "type": "integer", "example": 80000000 }, "seconds": { "type": "integer", "example": 42 } } }, "controllers.PatientContext": { "type": "object", "properties": { "dob": { "type": "string", "description": "**Optional** - Patient date of birth in `YYYY-MM-DD` format.", "example": "2000-01-01" }, "sex": { "type": "string", "description": "**Optional** - Patient sex. Accepted values: `male`, `female`, `other`.", "example": "male", "enum": [ "male", "female", "other", "unknown" ] } }, "description": "Patient demographics used to guide note generation." }, "controllers.PersonalizationPreference": { "type": "object", "properties": { "section_format": { "type": "array", "description": "Formatting preference per LOINC section. Each entry includes a `loinc` code and `style` (`NARRATIVE` or `BULLETED`).", "items": { "$ref": "#/components/schemas/controllers.SectionFormat" } }, "verbosity": { "type": "string", "description": "Controls detail level in generated notes. Accepted values: `CONCISE`, `BALANCED`, `DETAILED`.", "example": "CONCISE", "enum": [ "CONCISE", "BALANCED", "DETAILED" ] } }, "description": "Personalization settings for content generation" }, "controllers.Preference": { "type": "object", "properties": { "personalization_preference": { "type": "object", "description": "**Optional** - Personalization settings such as note verbosity and section format.", "allOf": [ { "$ref": "#/components/schemas/controllers.PersonalizationPreference" } ] } }, "description": "Personalization settings to create or update for the authenticated user." }, "controllers.ProviderContext": { "type": "object", "properties": { "provider_role": { "type": "string", "description": "Provider role for the session. Call `GET /api/v1/info/provider-roles` for supported values.", "example": "ATTENDING", "enum": [ "ATTENDING", "CONSULTING" ] }, "specialty": { "type": "string", "description": "**Optional** - Provider medical specialty. Call `GET /api/v1/info/specialties` for supported values.", "example": "CARDIOLOGY" } } }, "controllers.PublicKeyData": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/controllers.KeyData" }, "description": "Array of JSON Web Keys used to verify partner token signatures." } }, "description": "JSON Web Key Set document for partner token verification." }, "controllers.RegistrationRequest": { "type": "object", "required": [ "partner_id", "partner_token", "provider_name", "provider_org_id" ], "properties": { "partner_id": { "type": "string", "description": "Unique identifier for the partner. This will be shared securely by Suki to the partner through a separate partner registration process.", "example": "your-partner-id" }, "partner_token": { "type": "string", "description": "JWT token issued by trusted authorization server. The token must include Provider Email.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "provider_id": { "type": "string", "description": "**Optional** - Unique identifier for the provider. This is required for Bearer type partners only and will be ignored for other partner types. This must match a pre-defined expression.", "example": "provider-123" }, "provider_name": { "type": "string", "description": "Name of the provider.", "example": "Dr. John Smith" }, "provider_org_id": { "type": "string", "description": "Health system or organization to which the provider belongs.", "example": "org-123" }, "provider_specialty": { "type": "string", "description": "**Optional** - Medical specialty of the provider. Defaults to FAMILY_MEDICINE if not provided.", "example": "CARDIOLOGY" } }, "description": "Provider registration details and partner credentials from onboarding.", "example": { "partner_id": "your-partner-id", "partner_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "provider_id": "provider-123", "provider_name": "Dr. John Smith", "provider_org_id": "org-123", "provider_specialty": "CARDIOLOGY" } }, "controllers.Route": { "type": "object", "properties": { "raw_value": { "type": "string", "description": "(Optional) Raw administration route", "example": "Oral" } } }, "controllers.Strength": { "type": "object", "properties": { "raw_value": { "type": "string", "description": "(Optional) Raw strength value", "example": "500mg" } } }, "controllers.SectionContext": { "type": "object", "required": [ "loinc" ], "properties": { "loinc": { "type": "string", "description": "LOINC code for the section. Supported Loinc codes are available at: [note-sections](/documentation/note-sections)", "example": "10164-2" } } }, "controllers.VisitContext": { "type": "object", "properties": { "chief_complaint": { "type": "string", "description": "Captures the initial problem the patient presents with", "example": "Headache (Patient's primary symptom or problem stated in their own words)" }, "encounter_type": { "type": "string", "description": "Encounter setting, such as AMBULATORY or INPATIENT. Call `GET /api/v1/info/encounter-types` for supported values.", "example": "AMBULATORY", "enum": [ "AMBULATORY", "INPATIENT", "EMERGENCY" ] }, "reason_for_visit": { "type": "string", "description": "Specific symptom / condition, or request (e.g., chest pain, wellness exam)", "example": "Follow-up for migraines" }, "visit_type": { "type": "string", "description": "Visit category, such as NEW_PATIENT or ESTABLISHED_PATIENT. Call `GET /api/v1/info/visit-types` for supported values.", "example": "ESTABLISHED_PATIENT", "enum": [ "NEW_PATIENT", "ESTABLISHED_PATIENT", "WELLNESS", "ED" ] } }, "description": "Visit details such as chief complaint, encounter type, and visit type." }, "controllers.SectionFormat": { "type": "object", "properties": { "loinc": { "type": "string", "description": "LOINC code identifying the clinical section", "example": "10164-2" }, "style": { "type": "string", "description": "Preferred formatting style for the section\nPossible values: NARRATIVE, BULLETED", "example": "NARRATIVE", "enum": [ "NARRATIVE", "BULLETED" ] } }, "description": "Style preferences for a specific clinical section" }, "controllers.SessionContentResponse": { "type": "object", "properties": { "structured_data": { "type": "array", "description": "Structured data extracted from the ambient session.", "items": { "$ref": "#/components/schemas/controllers.StructuredDataBlock" } }, "summary": { "type": "array", "description": "Summary of the ambient session.", "items": { "$ref": "#/components/schemas/controllers.ContentBlock" } } }, "description": "Response body for the /session/{ambient_session_id}/content endpoint" }, "controllers.SessionMetadata": { "type": "object", "properties": { "note_sections": { "type": "array", "description": "**Optional** - Default note sections used if not provided", "items": { "$ref": "#/components/schemas/controllers.NoteSection" } }, "patient_dob": { "type": "string", "description": "**Optional** - {YYYY-MM-DD}", "example": "2000-01-01" }, "patient_sex": { "type": "string", "description": "**Optional**", "example": "male", "enum": [ "male", "female", "other", "unknown" ] }, "provider_specialty": { "type": "string", "description": "**Optional** - Defaults to FAMILY_MEDICINE if not provided", "example": "CARDIOLOGY" } }, "description": "Session metadata for the ambient session. **Deprecated.** Use context APIs instead." }, "controllers.SessionStructuredDataResponse": { "type": "object", "properties": { "structured_data": { "$ref": "#/components/schemas/controllers.StructuredData" } }, "description": "Response body for the /session/{ambient_session_id}/structured-data endpoint" }, "controllers.SpecialtyCodesResponse": { "type": "object", "properties": { "specialties": { "type": "array", "description": "Information about supported specialties", "items": { "$ref": "#/components/schemas/controllers.SpecialtyInfo" } } }, "description": "Response body for the /info/specialties endpoint" }, "controllers.EncounterTypesResponse": { "type": "object", "properties": { "encounter_types": { "type": "array", "description": "List of supported encounter types", "items": { "$ref": "#/components/schemas/controllers.EncounterTypeInfo" } } }, "description": "Response body for the /info/encounter-types endpoint" }, "controllers.VisitTypesResponse": { "type": "object", "properties": { "visit_types": { "type": "array", "description": "List of supported visit types", "items": { "$ref": "#/components/schemas/controllers.VisitTypeInfo" } } }, "description": "Response body for the /info/visit-types endpoint" }, "controllers.ProviderRolesResponse": { "type": "object", "properties": { "provider_roles": { "type": "array", "description": "List of supported provider roles", "items": { "$ref": "#/components/schemas/controllers.ProviderRoleInfo" } } }, "description": "Response body for the /info/provider-roles endpoint" }, "controllers.SpecialtyInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "Specialty code (e.g., \"CARDIOLOGY\", \"FAMILY_MEDICINE\")", "example": "CARDIOLOGY" } }, "description": "Information about a medical specialty" }, "controllers.EncounterTypeInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "Encounter type code (e.g., \"AMBULATORY\", \"INPATIENT\", \"EMERGENCY\")", "example": "AMBULATORY" } }, "description": "Information about an encounter type" }, "controllers.ProviderRoleInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "Provider role code (e.g., \"ATTENDING\", \"CONSULTING\")", "example": "ATTENDING" } }, "description": "Information about a provider role" }, "controllers.VisitTypeInfo": { "type": "object", "properties": { "code": { "type": "string", "description": "Visit type code (e.g., \"NEW_PATIENT\", \"ESTABLISHED_PATIENT\", \"WELLNESS\", \"ED\")", "example": "ESTABLISHED_PATIENT" } }, "description": "Information about a visit type" }, "controllers.StatusResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Processing state of the ambient session. Poll until the status is `completed`, `failed`, or `aborted`.", "example": "completed", "enum": [ "created", "ready", "running", "paused", "aborted", "failed", "completed" ] } }, "description": "Current processing status for an ambient session." }, "controllers.FormFillingStatusResponse": { "type": "object", "description": "Current processing status for a form-filling session.", "properties": { "status": { "type": "string", "description": "Processing state of the form-filling session. Poll until the status is `completed`, `failed`, or `aborted`.", "example": "completed", "enum": [ "created", "ready", "running", "paused", "aborted", "failed", "completed" ] } } }, "controllers.StructuredData": { "type": "object", "properties": { "diagnoses": { "$ref": "#/components/schemas/controllers.Diagnoses" }, "orders": { "$ref": "#/components/schemas/controllers.Orders" } } }, "controllers.StructuredDataBlock": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The structured data in the block. This is a key-value pair where the key is the name of the data and the value is the data itself.\nFor example, for medications, the key can be the name of the medication and the value can be the dosage.\nThis is kept as map since we don't know the structure of the data that will be extracted.", "example": { "dosage": "2 puffs", "medication": "albuterol" } }, "title": { "type": "string", "description": "The title of the structured data block. Usually refers to names like Medications, Allergies, etc.", "example": "MEDICATIONS" } } }, "controllers.SuccessNotification": { "type": "object", "properties": { "_links": { "type": "object", "description": "Links to associated resources.", "allOf": [ { "$ref": "#/components/schemas/controllers.Links" } ] }, "additional_info": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Any Additional information about the notification.", "example": { "priority": "high" } }, "encounter_id": { "type": "string", "description": "Id of the encounter to which the payload belongs.", "example": "4d753ce1-bbff-43e1-950a-82dea2d86873" }, "session_id": { "type": "string", "description": "Id of the session for which the notification is being sent.", "example": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2" }, "sessions": { "type": "array", "description": "Sorted list of sessions that occured within an encounter in the order of\noccurence.", "example": [ "20965414-929a-4f71-a3e5-b92bec07d086", "29de56bc-960a-4cd5-b18f-79a798d62874" ], "items": { "type": "string" } }, "status": { "type": "string", "example": "success" } }, "description": "Webhook payload Suki sends when session processing succeeds." }, "controllers.UpdateContextRequest": { "type": "object", "properties": { "diagnoses": { "type": "object", "description": "**Optional** - Diagnoses to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.DiagnosesContext" } ] }, "emr": { "type": "object", "description": "**Optional** - EMR context to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.EmrContext" } ] }, "orders": { "type": "object", "description": "**Optional** - Medication orders to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.OrdersContext" } ] }, "patient": { "type": "object", "description": "**Optional** - Patient demographics to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.PatientContext" } ] }, "provider": { "type": "object", "description": "**Optional** - Provider details to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.ProviderContext" } ] }, "sections": { "type": "array", "description": "**Optional** - Information about the sections to be generated.\nIf not provided, all supported [note-sections](/documentation/note-sections) will be generated.", "items": { "$ref": "#/components/schemas/controllers.SectionContext" } }, "visit": { "type": "object", "description": "**Optional** - Visit details to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.VisitContext" } ] } }, "description": "Partial ambient session context update. Include only the fields you want to add or change.", "example": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "ATHENA" }, "orders": { "medication_orders": { "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "metadata": { "encounter_relation": "CURRENT_ENCOUNTER", "origin": "SUKI_AMBIENT" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } }, "patient": { "dob": "2000-01-01", "sex": "male" }, "provider": { "role": "ATTENDING", "specialty": "CARDIOLOGY" }, "sections": [ { "loinc": "10164-2" } ], "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" } } }, "controllers.UpdateContextResponse": { "type": "object", "properties": { "context": { "type": "object", "description": "Updated context for the session", "allOf": [ { "$ref": "#/components/schemas/controllers.Context" } ] } }, "description": "Updated ambient session context after a successful PATCH.", "example": { "context": { "diagnoses": { "values": [ { "codes": [ { "code": "30422", "description": "Essential hypertension", "type": "IMO" } ], "diagnosis_note": "Hypertension" } ] }, "emr": { "target_emr": "ATHENA" }, "orders": { "medication_orders": { "values": [ { "dosage": { "quantity": 1, "raw_value": "1 tablet", "unit": "TAB" }, "drug_name": "Acetaminophen 500mg Tab", "duration_in_days": 7, "end_date": "2026-01-08T00:00:00Z", "format": { "raw_value": "Tablet" }, "frequency": { "raw_value": "once daily", "structured_value": "ONE_A_DAY" }, "instructions": "Take with food", "linked_diagnosis_codes": [ { "code": "I10", "type": "ICD10" } ], "medication_code": { "code": "860975", "type": "RXCUI" }, "medication_timing": { "raw_value": "morning", "structured_value": "IN_THE_MORNING" }, "metadata": { "encounter_relation": "CURRENT_ENCOUNTER", "origin": "SUKI_AMBIENT" }, "number_of_refills": 3, "quantity_dispensed": "1 box", "route": { "raw_value": "Oral" }, "start_date": "2026-01-01T00:00:00Z", "status": "ACTIVE", "strength": { "raw_value": "500mg" } } ] } }, "patient": { "dob": "2000-01-01", "sex": "male" }, "provider": { "role": "ATTENDING", "specialty": "CARDIOLOGY" }, "sections": [ { "loinc": "10164-2" } ], "visit": { "chief_complaint": "Headache", "encounter_type": "AMBULATORY", "reason_for_visit": "Follow-up for migraines", "visit_type": "ESTABLISHED_PATIENT" } } } }, "controllers.FormFillingReturnedContext": { "description": "Updated session context returned by form-filling context PATCH. Form-filling only; not used by ambient session context APIs.", "type": "object", "properties": { "form_filling": { "type": "object", "description": "**Optional** - Form template metadata for the session", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingContext" } ] } } }, "controllers.FormFillingUpdateContextResponse": { "type": "object", "properties": { "context": { "type": "object", "description": "Updated context for the form-filling session", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingReturnedContext" } ] } }, "description": "Response body for the /api/v1/form-filling/session/{ambient_session_id}/context PATCH endpoint", "example": { "context": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } } }, "controllers.UpdateUserPreferencesResponse": { "type": "object", "properties": { "preference": { "type": "object", "description": "Updated user preference settings", "allOf": [ { "$ref": "#/components/schemas/controllers.Preference" } ] } }, "description": "Response body for the /user/preferences endpoint", "example": { "preference": { "personalization_preference": { "section_format": [ { "loinc": "10164-2", "style": "NARRATIVE" } ], "verbosity": "CONCISE" } } } }, "controllers.FeedbackRequest": { "type": "object", "required": [ "ratingFeedback" ], "properties": { "ratingFeedback": { "type": "object", "required": [ "min_rating", "max_rating", "rating" ], "properties": { "min_rating": { "type": "integer", "description": "Minimum rating value - you can choose any number as the minimum i.e 0 and above", "example": 0 }, "max_rating": { "type": "integer", "description": "Maximum rating value - you can choose any number that is greater than the minimum value", "example": 1 }, "rating": { "type": "integer", "minimum": 0, "maximum": 1, "description": "The actual rating given within the min-max range", "example": 1 } }, "description": "Required quantitative rating. Set `min_rating`, `max_rating`, and `rating` to define the scale and score." }, "qualitative_comments": { "type": "string", "maxLength": 2000, "description": "**Optional** - Qualitative feedback comments for detailed insights. Maximum 2000 characters allowed.", "example": "The generated content was accurate and helpful" } }, "description": "Quantitative rating and optional qualitative comments for the specified entity." }, "controllers.FeedbackResponse": { "type": "object", "properties": { "feedback_id": { "type": "string", "description": "Unique identifier for the submitted feedback", "example": "fb_abc123def456-789xyz-012uvw" } }, "description": "Response body for successful feedback submission" }, "controllers.AllOrderInfoResponse": { "description": "Response body for the /info/orders endpoint", "type": "object", "properties": { "coding_systems": { "description": "Information about supported medication coding systems", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationCodingSystemInfo" } }, "dosage_units": { "description": "Information about supported dosage units", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationDosageUnitInfo" } }, "encounter_relations": { "description": "Information about supported order encounter relations", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderEncounterRelationInfo" } }, "frequency_types": { "description": "Information about supported frequency types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationFrequencyTypeInfo" } }, "origins": { "description": "Information about supported order origins", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderOriginInfo" } }, "statuses": { "description": "Information about supported medication order statuses", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderStatusInfo" } }, "timings": { "description": "Information about supported medication timings", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationTimingInfo" } } } }, "controllers.MedicationCode": { "type": "object", "properties": { "code": { "type": "string", "description": "(*Required) Medication code value", "example": "860975" }, "type": { "type": "string", "description": "(*Required) Medication coding system", "enum": [ "RXCUI", "NDC" ], "example": "RXCUI" } } }, "controllers.MedicationCodingSystemInfo": { "description": "Information about a medication coding system", "type": "object", "properties": { "code": { "description": "Coding system code (e.g., \"RXCUI\", \"NDC\")", "type": "string", "example": "RXCUI" } } }, "controllers.MedicationCodingSystemsResponse": { "description": "Response body for the /info/orders/coding-systems endpoint", "type": "object", "properties": { "coding_systems": { "description": "Information about supported medication coding systems", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationCodingSystemInfo" } } } }, "controllers.MedicationDosageUnitInfo": { "description": "Information about a medication dosage unit", "type": "object", "properties": { "code": { "description": "Dosage unit code (e.g., \"TAB\", \"TBSP\")", "type": "string", "example": "TAB" } } }, "controllers.MedicationDosageUnitsResponse": { "description": "Response body for the /info/orders/dosage-units endpoint", "type": "object", "properties": { "dosage_units": { "description": "Information about supported dosage units", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationDosageUnitInfo" } } } }, "controllers.MedicationFrequencyTypeInfo": { "description": "Information about a medication frequency type", "type": "object", "properties": { "code": { "description": "Frequency type code (e.g., \"ONE_A_DAY\", \"TWO_A_DAY\")", "type": "string", "example": "ONE_A_DAY" } } }, "controllers.MedicationFrequencyTypesResponse": { "description": "Response body for the /info/orders/frequencies endpoint", "type": "object", "properties": { "frequency_types": { "description": "Information about supported frequency types", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationFrequencyTypeInfo" } } } }, "controllers.MedicationOrderRequest": { "type": "object", "required": [ "drug_name", "medication_code", "status", "metadata" ], "properties": { "dosage": { "type": "object", "description": "**Optional** - Amount per administration", "allOf": [ { "$ref": "#/components/schemas/controllers.Dosage" } ] }, "drug_name": { "type": "string", "description": "**Required** - Full medication name", "example": "Acetaminophen 500mg Tab" }, "duration_in_days": { "type": "integer", "description": "**Optional** - Duration in days", "example": 7 }, "end_date": { "type": "string", "description": "**Optional** - End date-time (RFC3339)", "example": "2026-01-08T00:00:00Z" }, "format": { "type": "object", "description": "**Optional** - Physical dosage form", "allOf": [ { "$ref": "#/components/schemas/controllers.Format" } ] }, "frequency": { "type": "object", "description": "**Optional** - Administration frequency", "allOf": [ { "$ref": "#/components/schemas/controllers.Frequency" } ] }, "instructions": { "type": "string", "description": "**Optional** - Free-form instructions", "example": "Take with food" }, "linked_diagnosis_codes": { "type": "array", "description": "**Optional** - Diagnosis codes linked to this order. When provided, each entry should match a diagnosis already supplied under `diagnoses` (same coding system) so the platform can validate the link.", "items": { "$ref": "#/components/schemas/controllers.LinkedDiagnosisCode" } }, "medication_code": { "type": "object", "description": "**Required** - Standardized medication code (`code` and `type` are both required; see `MedicationCode`)", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationCode" } ] }, "medication_timing": { "type": "object", "description": "**Optional** - Timing modifiers", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationTiming" } ] }, "metadata": { "type": "object", "description": "**Required** - Order metadata. **`origin`** is required (`EMR` or `SUKI_AMBIENT`). **`encounter_relation`** is **required** when **`origin`** is **`EMR`** (see `OrderMetadata`).", "allOf": [ { "$ref": "#/components/schemas/controllers.OrderMetadata" } ] }, "number_of_refills": { "type": "integer", "description": "**Optional** - Number of refills", "example": 3 }, "quantity_dispensed": { "type": "string", "description": "**Optional** - Quantity dispensed", "example": "1 box" }, "route": { "type": "object", "description": "**Optional** - Administration route", "allOf": [ { "$ref": "#/components/schemas/controllers.Route" } ] }, "start_date": { "type": "string", "description": "**Optional** - Start date-time (RFC3339)", "example": "2026-01-01T00:00:00Z" }, "status": { "type": "string", "description": "**Required** - Order status", "enum": [ "ACTIVE", "DISCONTINUED", "REFILLED" ], "example": "ACTIVE" }, "strength": { "type": "object", "description": "**Optional** - Medication strength or concentration (`raw_value` until standardized values are finalized)", "allOf": [ { "$ref": "#/components/schemas/controllers.Strength" } ] } } }, "controllers.MedicationOrderResponse": { "type": "object", "properties": { "dosage": { "type": "object", "description": "Amount per administration", "allOf": [ { "$ref": "#/components/schemas/controllers.Dosage" } ] }, "drug_name": { "type": "string", "description": "Full medication name", "example": "Acetaminophen 500mg Tab" }, "duration_in_days": { "type": "integer", "description": "Duration in days", "example": 7 }, "end_date": { "type": "string", "description": "End date-time (RFC3339)", "example": "2026-01-08T00:00:00Z" }, "format": { "type": "object", "description": "Physical dosage form", "allOf": [ { "$ref": "#/components/schemas/controllers.Format" } ] }, "frequency": { "type": "object", "description": "Administration frequency", "allOf": [ { "$ref": "#/components/schemas/controllers.Frequency" } ] }, "instructions": { "type": "string", "description": "Free-form instructions", "example": "Take with food" }, "linked_diagnosis_codes": { "type": "array", "description": "Linked ICD10 diagnosis codes", "items": { "$ref": "#/components/schemas/controllers.LinkedDiagnosisCode" } }, "medication_code": { "type": "object", "description": "Standardized medication code", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationCode" } ] }, "medication_timing": { "type": "object", "description": "Timing modifiers", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationTiming" } ] }, "number_of_refills": { "type": "integer", "description": "Number of refills", "example": 3 }, "quantity_dispensed": { "type": "string", "description": "Quantity dispensed", "example": "1 box" }, "route": { "type": "object", "description": "Administration route", "allOf": [ { "$ref": "#/components/schemas/controllers.Route" } ] }, "start_date": { "type": "string", "description": "Start date-time (RFC3339)", "example": "2026-01-01T00:00:00Z" }, "status": { "type": "string", "description": "Order status", "enum": [ "ACTIVE", "DISCONTINUED", "REFILLED" ], "example": "ACTIVE" }, "strength": { "type": "object", "description": "Medication strength or concentration", "allOf": [ { "$ref": "#/components/schemas/controllers.Strength" } ] } } }, "controllers.MedicationOrders": { "type": "object", "properties": { "partial_values": { "type": "array", "description": "Medication Orders that are not submittable (Criteria decided based on target_emr provided in EmrContext)", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderResponse" } }, "values": { "type": "array", "description": "Emr Submittable medication Orders (Criteria decided based on target_emr provided in EmrContext)", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderResponse" } } } }, "controllers.MedicationOrdersContext": { "type": "object", "properties": { "values": { "type": "array", "description": "**Optional** - Medication order requests", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderRequest" } } } }, "controllers.MedicationOrderStatusInfo": { "description": "Information about a medication order status", "type": "object", "properties": { "code": { "description": "Medication order status code (e.g., \"ACTIVE\", \"DISCONTINUED\")", "type": "string", "example": "ACTIVE" } } }, "controllers.MedicationOrderStatusesResponse": { "description": "Response body for the /info/orders/statuses endpoint", "type": "object", "properties": { "statuses": { "description": "Information about supported medication order statuses", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderStatusInfo" } } } }, "controllers.MedicationTiming": { "type": "object", "properties": { "raw_value": { "type": "string", "description": "(Optional) Raw timing text", "example": "morning" }, "structured_value": { "type": "string", "description": "(Optional) Medication timing enum", "example": "IN_THE_MORNING" } } }, "controllers.MedicationTimingInfo": { "description": "Information about a medication timing", "type": "object", "properties": { "code": { "description": "Medication timing code (e.g., \"WITH_MEALS\")", "type": "string", "example": "WITH_MEALS" } } }, "controllers.MedicationTimingsResponse": { "description": "Response body for the /info/orders/medication-timings endpoint", "type": "object", "properties": { "timings": { "description": "Information about supported medication timings", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationTimingInfo" } } } }, "controllers.OrderEncounterRelationInfo": { "description": "Information about an order encounter relation", "type": "object", "properties": { "code": { "description": "Encounter relation code (e.g., \"CURRENT_ENCOUNTER\", \"PRIOR_ENCOUNTER\")", "type": "string", "example": "CURRENT_ENCOUNTER" } } }, "controllers.OrderEncounterRelationsResponse": { "description": "Response body for the /info/orders/encounter-relations endpoint", "type": "object", "properties": { "encounter_relations": { "description": "Information about supported order encounter relations", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderEncounterRelationInfo" } } } }, "controllers.OrderOriginInfo": { "description": "Information about an order origin", "type": "object", "properties": { "code": { "description": "Order origin code (e.g., \"SUKI_AMBIENT\", \"EMR\")", "type": "string", "example": "SUKI_AMBIENT" } } }, "controllers.OrderOriginsResponse": { "description": "Response body for the /info/orders/origins endpoint", "type": "object", "properties": { "origins": { "description": "Information about supported order origins", "type": "array", "items": { "$ref": "#/components/schemas/controllers.OrderOriginInfo" } } } }, "controllers.OrderMetadata": { "type": "object", "required": [ "origin" ], "properties": { "encounter_relation": { "type": "string", "description": "**Required when `origin` is `EMR`** - How this order relates to the encounter. Set to **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.", "enum": [ "CURRENT_ENCOUNTER", "PRIOR_ENCOUNTER" ], "example": "CURRENT_ENCOUNTER" }, "origin": { "type": "string", "description": "**Required** - Source of the order", "enum": [ "EMR", "SUKI_AMBIENT" ], "example": "SUKI_AMBIENT" } } }, "controllers.Orders": { "type": "object", "properties": { "medication_orders": { "type": "object", "description": "Medication orders structured data", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationOrders" } ] } } }, "controllers.OrdersContext": { "type": "object", "properties": { "medication_orders": { "type": "object", "description": "**Optional** - Medication orders supplied in context", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationOrdersContext" } ] } } }, "controllers.CreateFormFillingSessionResponse": { "description": "New form-filling session ID returned after create.", "type": "object", "properties": { "ambient_session_id": { "type": "string", "description": "Form-filling session ID for subsequent form-filling API calls. Despite the field name, this is not an ambient clinical documentation session ID.", "example": "123dfg-456dfg-789dfg-012dfg" } } }, "controllers.CreateFormFillingSessionRequest": { "description": "Optional form-filling session ID and correlation metadata. Suki generates a form-filling session ID when omitted.", "type": "object", "properties": { "ambient_session_id": { "type": "string", "description": "**Optional** - Form-filling session ID in UUID format. Suki generates one when omitted and returns it in the `ambient_session_id` response field. Do not pass an ambient clinical documentation session ID.", "example": "123dfg-456dfg-789dfg-012dfg" }, "correlation_id": { "type": "string", "description": "**Optional** - Client-supplied identifier for tracing or correlating requests.", "example": "123dfg-456dfg-789dfg-012dfg" } } }, "controllers.FormFillingStructuredDataResponse": { "description": "Structured medical form output for a form-filling session.", "type": "object", "properties": { "structured_data": { "$ref": "#/components/schemas/controllers.FormFillingStructuredData" } }, "example": { "structured_data": { "generated_values": [ { "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "data": { "additionalProp1": {} }, "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template", "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "metadata": { "additionalProp1": {} }, "patient_id": "patient-123", "status": "MEDICAL_FORM_STATUS_COMPLETED", "title": "Adult Vitals", "type": "VITALS_ASSESSMENT" } ], "non_generated_values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } }, "controllers.FormFillingStructuredData": { "description": "Medical form instances for a form-filling session (full generated values and sparse non-generated entries).", "type": "object", "properties": { "generated_values": { "type": "array", "items": { "$ref": "#/components/schemas/controllers.FormFillingGeneratedMedicalFormInstance" } }, "non_generated_values": { "type": "array", "items": { "$ref": "#/components/schemas/controllers.FormFillingNonGeneratedMedicalFormInstance" } } } }, "controllers.FormFillingGeneratedMedicalFormInstance": { "description": "Generated medical form instance returned for a form-filling session.", "type": "object", "properties": { "correlation_id": { "type": "string", "example": "20965414-929a-4f71-a3e5-b92bec07d086" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" }, "data": { "type": "object", "additionalProperties": true, "example": { "additionalProp1": {} } }, "form_template_id": { "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template" }, "id": { "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "additionalProp1": {} } }, "patient_id": { "type": "string", "example": "patient-123" }, "status": { "type": "string", "example": "MEDICAL_FORM_STATUS_COMPLETED" }, "title": { "type": "string", "example": "Adult Vitals" }, "type": { "type": "string", "example": "VITALS_ASSESSMENT" } } }, "controllers.FormFillingNonGeneratedMedicalFormInstance": { "description": "Medical form template that did not produce generated values.", "type": "object", "properties": { "form_template_id": { "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } } }, "controllers.FormFillingContext": { "type": "object", "description": "Information about form-filling context", "required": [ "values" ], "properties": { "values": { "description": "Array of form template metadata.", "type": "array", "items": { "$ref": "#/components/schemas/controllers.FormFillingMetadata" } } } }, "controllers.FormFillingMetadata": { "type": "object", "required": [ "form_template_id" ], "properties": { "form_template_id": { "description": "Form template ID (UUID).", "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } } }, "controllers.SubmitFeedbackResponse": { "description": "Response body for /api/v1/form-filling/session/{ambient_session_id}/{entity}/feedback.", "type": "object", "properties": { "feedback_id": { "description": "feedback identifier", "type": "string" } } }, "controllers.GetSukiFormTemplatesResponse": { "description": "Response body for the /info/suki-medical-form-templates endpoint", "type": "object", "properties": { "form_templates": { "description": "List of Suki-defined medical form templates", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicalFormTemplate" } } } }, "controllers.MedicalFormTemplateSchemaOption": { "description": "Selectable option for a form template field (for example radio or dropdown choices).", "type": "object", "properties": { "code": { "description": "**Optional** - Option code when provided; may be null for display-only choices.", "type": "string", "nullable": true, "example": null }, "display": { "description": "Human-readable option label shown in the form UI.", "type": "string", "example": "Regular" } } }, "controllers.MedicalFormTemplateSchemaItem": { "description": "A single field or question definition inside a medical form template schema.", "type": "object", "properties": { "code": { "description": "Question or field code.", "type": "string", "example": "Q003" }, "id": { "description": "Stable field identifier within the template.", "type": "string", "example": "respiratory_pattern" }, "kind": { "description": "Item kind (for example `field`).", "type": "string", "example": "field" }, "options": { "description": "**Optional** - Choices for selection-style fields (for example `radio`).", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicalFormTemplateSchemaOption" } }, "pattern": { "description": "**Optional** - Validation pattern when applicable.", "type": "string", "example": "" }, "question": { "description": "Question or field label text.", "type": "string", "example": "Respiratory Pattern / Effort" }, "type": { "description": "Input type (for example `radio`, `text`).", "type": "string", "example": "radio" } } }, "controllers.MedicalFormTemplateSchema": { "description": "Object describing the structure of a medical form template, including its field definitions.", "type": "object", "properties": { "items": { "description": "Ordered list of template fields and questions.", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicalFormTemplateSchemaItem" } } } }, "controllers.MedicalFormTemplate": { "description": "Suki-defined medical form template", "type": "object", "properties": { "description": { "description": "**Optional** - Free-text description", "type": "string", "example": "Standard vitals collection template for adult patients." }, "name": { "description": "Human-readable template name", "type": "string", "example": "Adult Vitals" }, "schema": { "description": "Template structure: an object with an `items` array of field definitions.", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicalFormTemplateSchema" } ] }, "template_id": { "description": "Unique identifier for this template version", "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, "type": { "description": "Type classification (e.g., VITALS_ASSESSMENT, SKIN_ASSESSMENT)", "type": "string", "example": "VITALS_ASSESSMENT" } }, "example": { "description": "Standard vitals collection template for adult patients.", "name": "Adult Vitals", "template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "type": "VITALS_ASSESSMENT", "schema": { "items": [ { "code": "Q003", "id": "respiratory_pattern", "kind": "field", "options": [ { "code": null, "display": "Regular" }, { "code": null, "display": "Shallow" }, { "code": null, "display": "Deep" }, { "code": null, "display": "Labored" }, { "code": null, "display": "Tachypneic (rapid breathing)" }, { "code": null, "display": "Bradypneic (slow breathing)" }, { "code": null, "display": "Irregular" }, { "code": null, "display": "Apneic (no spontaneous breathing)" } ], "pattern": "", "question": "Respiratory Pattern / Effort", "type": "radio" } ] } } }, "controllers.Feedback": { "type": "object", "properties": { "qualitative_comments": { "description": "Freeform text comments.", "type": "string", "maxLength": 2000, "example": "Accurate and well-structured form output." }, "ratingFeedback": { "description": "Present for Likert or binary scales (`min_rating`, `max_rating`, `rating`).", "allOf": [ { "$ref": "#/components/schemas/controllers.QuantitativeFeedback" } ] } } }, "controllers.FormFillingFeedbackMetadata": { "description": "Metadata required for form-filling feedback when entity is `AMBIENT_GENERATED_MEDICAL_FORM` (identifies which medical form instance the feedback refers to).", "type": "object", "required": [ "form_id" ], "properties": { "form_id": { "description": "Medical form instance ID used to load full form details server-side.", "type": "string", "example": "018f94e8-7aa8-7bfd-bc83-046262001234" } } }, "controllers.FormFillingFeedbackPayload": { "description": "Quantitative rating and optional qualitative comments for the specified form-filling entity.", "type": "object", "required": [ "feedback" ], "properties": { "feedback": { "description": "Required quantitative and qualitative feedback.", "allOf": [ { "$ref": "#/components/schemas/controllers.Feedback" } ] }, "feedback_metadata": { "description": "Required when entity is `AMBIENT_GENERATED_MEDICAL_FORM`.", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingFeedbackMetadata" } ] } }, "example": { "feedback": { "qualitative_comments": "Accurate and well-structured form output.", "ratingFeedback": { "min_rating": 1, "max_rating": 5, "rating": 5 } }, "feedback_metadata": { "form_id": "018f94e8-7aa8-7bfd-bc83-046262001234" } } }, "controllers.QuantitativeFeedback": { "description": "Quantitative feedback for the session", "type": "object", "properties": { "max_rating": { "type": "integer", "description": "Maximum rating value - you can choose any number that is greater than the minimum value" }, "min_rating": { "type": "integer", "description": "Minimum rating value - you can choose any number as the minimum i.e 0 and above" }, "rating": { "type": "integer", "description": "The actual rating given within the min-max range" } } }, "controllers.FormFillingSessionContext": { "type": "object", "properties": { "form_filling": { "description": "**Optional** - Form template metadata for the form-filling session, including required `form_template_id` values.", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingContext" } ] } }, "description": "Form template metadata for the form-filling session, including `form_filling.values` with required `form_template_id` entries." }, "controllers.FormFillingUpdateContextRequest": { "type": "object", "properties": { "form_filling": { "description": "**Optional** - Form template metadata to add or update.", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingContext" } ] } }, "description": "Partial form-filling context update. Include only the fields you want to change." } }, "securitySchemes": { "SukiTokenAuth": { "type": "apiKey", "in": "header", "name": "sdp_suki_token", "description": "Suki access token for the authenticated provider. Obtain this by calling Login or Register with a valid `partner_token`. Pass the `suki_token` value from the JSON response as the `sdp_suki_token` header on REST requests and non-browser WebSocket upgrades. Browser WebSocket clients pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after one hour; call Login again to refresh." } }, "parameters": { "ProviderIdHeader": { "name": "sdp_provider_id", "in": "header", "description": "**Optional** - Stable identifier for the active provider. Omit for standard partners whose `partner_token` identifies the user. **Required** for Bearer partners and Single Auth Token authentication where multiple providers share one `partner_token`. Use the same `provider_id` you sent on Login or Register.", "required": false, "schema": { "type": "string", "example": "provider-123" } } } }, "x-original-swagger-version": "2.0", "security": [ { "SukiTokenAuth": [] } ] }