{ "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": "Creates an 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": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateSessionRequest" }, "example": { "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", "emr_encounter_id": "123dfg-456dfg-789dfg-012dfg", "encounter_id": "123dfg-456dfg-789dfg-012dfg" } } } }, "responses": { "201": { "description": "Resource created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.CreateSessionResponse" }, "example": { "ambient_session_id": "123dfg-456dfg-789dfg-012dfg", "note_id": "123dfg-456dfg-789dfg-012dfg" } } } }, "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. Browsers must use the same subprotocol the grpc-wsproxy maps to Authorization: 'SukiAmbientAuth,,' (comma-separated; token second, ambient session id third). Other subprotocol names are not mapped and typically yield 401.", "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 filling session context before audio capture. Send Suki template IDs, partner schemas, or both in `form_filling.values`. Each entry must include either `form_template_id` or `schema`, not both. The `values` array MUST contain at least one entry; seeding is required to generate filled forms.", "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" }, "examples": { "static": { "summary": "Static Suki templates", "value": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, { "form_template_id": "019d4cdc-aaaa-bbbb-cccc-dddddddddddd" } ] } } }, "dynamic": { "summary": "Dynamic partner schemas", "value": { "form_filling": { "values": [ { "id": "partner-wound-1", "name": "Wound Check", "type": "SKIN_ASSESSMENT", "schema": { "title": "Wound Check", "type": "object", "properties": { "wound_status": { "type": "string" } } } } ] } } }, "mixed": { "summary": "Mixed static and dynamic", "value": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, { "id": "partner-custom-1", "name": "Custom Partner Form", "type": "NEURO_ASSESSMENT", "schema": { "type": "object", "properties": { "gcs": { "type": "number" } } } } ] } } } } } }, "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": "Updates Form filling session context. Use the same `values` rules as seed context: each entry is either a Suki template or a partner schema. 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" }, "examples": { "static": { "summary": "Update with static templates", "value": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } }, "dynamic": { "summary": "Update with a dynamic schema", "value": { "form_filling": { "values": [ { "id": "partner-pain-1", "name": "Pain Form", "type": "PAIN_ASSESSMENT", "schema": { "title": "Pain", "type": "object", "properties": { "pain_score": { "type": "number" } } } } ] } } }, "mixed": { "summary": "Update with mixed entries", "value": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, { "id": "partner-custom-1", "name": "Custom Partner Form", "type": "NEURO_ASSESSMENT", "schema": { "type": "object", "properties": { "gcs": { "type": "number" } } } } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.FormFillingUpdateContextResponse" }, "examples": { "static": { "summary": "Static template context", "value": { "context": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } ] } } } }, "dynamic": { "summary": "Dynamic schema context", "value": { "context": { "form_filling": { "values": [ { "id": "partner-wound-1", "name": "Wound Check", "type": "SKIN_ASSESSMENT", "schema": { "title": "Wound Check", "type": "object", "properties": { "wound_status": { "type": "string" } } } } ] } } } }, "mixed": { "summary": "Mixed static and dynamic context", "value": { "context": { "form_filling": { "values": [ { "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, { "id": "partner-custom-1", "name": "Custom Partner Form", "type": "NEURO_ASSESSMENT", "schema": { "type": "object", "properties": { "gcs": { "type": "number" } } } } ] } } } } } } } }, "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. `generated_values` can include static template instances and dynamic schema instances. Correlate dynamic results by partner `id` or `name` when you supplied them; do not assume list order.", "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" }, "examples": { "static": { "summary": "Static template session", "value": { "structured_data": { "generated_values": [ { "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "data": {}, "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template", "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "metadata": {}, "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" } ] } } }, "dynamic": { "summary": "Dynamic schema session", "value": { "structured_data": { "generated_values": [ { "id": "partner-wound-1", "title": "Wound Check", "type": "SKIN_ASSESSMENT", "status": "", "patient_id": "patient-123", "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "form_template_id": "", "data": { "wound_status": "healing" }, "metadata": {} } ], "non_generated_values": [] } } }, "mixed": { "summary": "Mixed static and dynamic session", "value": { "structured_data": { "generated_values": [ { "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "data": {}, "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template", "id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "metadata": {}, "patient_id": "patient-123", "status": "MEDICAL_FORM_STATUS_COMPLETED", "title": "Adult Vitals", "type": "VITALS_ASSESSMENT" }, { "id": "partner-custom-1", "title": "Custom Partner Form", "type": "NEURO_ASSESSMENT", "status": "", "patient_id": "patient-123", "correlation_id": "20965414-929a-4f71-a3e5-b92bec07d086", "created_at": "2026-01-01T00:00:00Z", "form_template_id": "", "data": { "gcs": 15 }, "metadata": {} } ], "non_generated_values": [] } } } } } } }, "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": "Lists Suki Medical form templates. Use each `template_id` as `form_template_id` for static Form filling context. For partner-defined forms, send a `schema` in context instead.", "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": [] } ] } }, "/api/v1/ambient/encounter/{emr_encounter_id}/notes": { "get": { "tags": [ "/api/v1/ambient/encounter" ], "summary": "Lists notes for an EMR encounter.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" }, { "name": "emr_encounter_id", "in": "path", "required": true, "description": "EMR encounter id (UUID or non-UUID, at most 36 characters). Same value you pass as `emr_encounter_id` on Ambient session create for interoperable workflows.", "schema": { "type": "string", "maxLength": 36 } } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ListEncounterNotesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not Found", "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": [] } ] } }, "/api/v1/ambient/encounter/{emr_encounter_id}/info": { "get": { "tags": [ "/api/v1/ambient/encounter" ], "summary": "Gets resolved note → session hierarchy for an EMR encounter.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" }, { "name": "emr_encounter_id", "in": "path", "required": true, "description": "EMR encounter id (UUID or non-UUID, at most 36 characters). Same value you pass as `emr_encounter_id` on Ambient session create for interoperable workflows.", "schema": { "type": "string", "maxLength": 36 } } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.GetEncounterInfoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not Found", "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": [] } ] } }, "/api/v1/ambient/note/{note_id}/content": { "get": { "tags": [ "/api/v1/ambient/note" ], "summary": "Gets the content for a note.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" }, { "name": "note_id", "in": "path", "required": true, "description": "Note identifier. Use the `note_id` returned from Ambient session create.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.GetNoteContentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not Found", "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": [] } ] } }, "/api/v1/ambient/note/{note_id}/context": { "get": { "tags": [ "/api/v1/ambient/note" ], "summary": "Gets the ambient context for a note.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" }, { "name": "note_id", "in": "path", "required": true, "description": "Note identifier. Use the `note_id` returned from Ambient session create.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.GetNoteContextResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not Found", "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": [] } ] } }, "/api/v1/ambient/note/{note_id}/structured-data": { "get": { "tags": [ "/api/v1/ambient/note" ], "summary": "Gets the structured data for a note.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" }, { "name": "note_id", "in": "path", "required": true, "description": "Note identifier. Use the `note_id` returned from Ambient session create.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.GetNoteStructuredDataResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "404": { "description": "Not Found", "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": [] } ] } }, "/api/v1/fhir-push/upload-url": { "get": { "tags": [ "/api/v1/fhir-push" ], "summary": "GET /api/v1/fhir-push/upload-url?organization_id={uuid}&correlation_id={optional}", "description": "Request a pre-signed upload URL for uploading a FHIR bundle to Suki's Clinical Knowledge Graph (CKG) ingestion pipeline. This is Step 1 of the three-step CKG Data Ingestion workflow. The returned `upload_url` is valid for 15 minutes and accepts a PUT request with your FHIR bundle JSON (max 500 MB). Use the `transaction_id` from the response to poll processing status via GET /api/v1/fhir-push/status/{transaction_id}. FHIR data ingested through this API powers Patient Summary generation. Include consistent patient, encounter, and practitioner identifiers in your FHIR resources so they match the `fhir_encounter_id` and `fhir_practitioner_id` values used for generation and retrieval.", "parameters": [ { "name": "organization_id", "in": "query", "description": "Your partner organization ID for this organization, chosen at provisioning (required). It can be a UUID or non-UUID string. But not a Suki UUID.", "required": true, "schema": { "type": "string" } }, { "name": "correlation_id", "in": "query", "description": "**Optional** client-defined identifier for ordering or correlating uploads (max 128 chars). If omitted the server generates one.", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Upload URL returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id", "upload_url", "expires_at" ], "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for this upload transaction." }, "upload_url": { "type": "string", "description": "Pre-signed URL to PUT your FHIR bundle to (expires in ~15 minutes)." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the upload_url expires." }, "correlation_id": { "type": "string", "description": "Echo of client-supplied correlation_id or server-generated value." } } }, "examples": { "success": { "value": { "transaction_id": "dea454fe-fecb-4cf0-aaa7-fa84d19c28f8", "upload_url": "https://storage.googleapis.com/...", "expires_at": "2026-05-18T06:55:42Z", "correlation_id": "encounter-12345-upload-1" } } } } } }, "400": { "description": "Bad request. Missing or invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "401": { "description": "Unauthorized. Missing or invalid sdp_suki_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. Token lacks required scopes or access to the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The requested resource or organization was not found.", "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 -G \"https://sdp.suki-stage.com/api/v1/fhir-push/upload-url\" \\\n --data-urlencode \"organization_id=your-organization-id\" \\\n --data-urlencode \"correlation_id=encounter-abc-123\" \\\n -H \"Authorization: Bearer YOUR_SDP_SUKI_TOKEN\"\n" }, { "lang": "python", "label": "Python", "source": "import requests\nimport time\nimport json\n\nBASE_URL = \"https://sdp.suki.ai\"\nsdp_token = \"\"\norg_id = \"\"\n\n# Step 1: Request upload URL\nparams = {\"organization_id\": org_id, \"correlation_id\": \"encounter-abc-123\"}\nheaders = {\"Authorization\": f\"Bearer {sdp_token}\"}\n\nresp = requests.get(\n f\"{BASE_URL}/api/v1/fhir-push/upload-url\",\n params=params,\n headers=headers,\n timeout=30\n)\nresp.raise_for_status()\ndata = resp.json()\n\ntransaction_id = data[\"transaction_id\"]\nupload_url = data[\"upload_url\"]\n\nprint(f\"Transaction ID: {transaction_id}\")\n\n# Step 2: Upload FHIR bundle\nwith open(\"my-fhir-bundle.json\", \"rb\") as f:\n upload_resp = requests.put(\n upload_url,\n headers={\n \"Content-Type\": \"application/json\",\n \"x-goog-content-length-range\": \"0,524288000\"\n },\n data=f,\n timeout=300\n )\nupload_resp.raise_for_status()\nprint(\"Upload complete. Polling status...\")\n\n# Step 3: Poll status\nwhile True:\n status_resp = requests.get(\n f\"{BASE_URL}/api/v1/fhir-push/status/{transaction_id}\",\n headers=headers,\n timeout=30\n )\n status_data = status_resp.json()\n state = status_data[\"status\"]\n print(f\"Status: {state}\")\n \n if state in [\"COMPLETED\", \"FAILED\", \"ARCHIVED\"]:\n print(json.dumps(status_data, indent=2))\n break\n \n time.sleep(5)" }, { "lang": "javascript", "label": "TypeScript", "source": "import fs from \"fs\";\n\nconst BASE_URL = \"https://sdp.suki.ai\";\nconst sdpSukiToken = \"\";\nconst orgId = \"\";\n\n// Step 1: Request upload URL\nconst params = new URLSearchParams({\n organization_id: orgId,\n correlation_id: \"encounter-abc-123\",\n});\n\nconst resp = await fetch(`${BASE_URL}/api/v1/fhir-push/upload-url?${params}`, {\n headers: { Authorization: `Bearer ${sdpSukiToken}` },\n});\n\nif (!resp.ok) throw new Error(`Request failed: ${resp.status}`);\n\nconst data = await resp.json();\nconst transactionId = data.transaction_id;\nconst uploadUrl = data.upload_url;\n\nconsole.log(`Transaction ID: ${transactionId}`);\n\n// Step 2: Upload FHIR bundle\nconst bundleContent = fs.readFileSync(\"my-fhir-bundle.json\", \"utf-8\");\n\nconst uploadResp = await fetch(uploadUrl, {\n method: \"PUT\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-goog-content-length-range\": \"0,524288000\",\n },\n body: bundleContent,\n});\n\nif (!uploadResp.ok) throw new Error(`Upload failed: ${uploadResp.status}`);\n\nconsole.log(\"Upload complete. Polling status...\");\n\n// Step 3: Poll status\nwhile (true) {\n const statusResp = await fetch(\n `${BASE_URL}/api/v1/fhir-push/status/${transactionId}`,\n { headers: { Authorization: `Bearer ${sdpSukiToken}` } }\n );\n \n const statusData = await statusResp.json();\n console.log(`Status: ${statusData.status}`);\n \n if ([\"COMPLETED\", \"FAILED\", \"ARCHIVED\"].includes(statusData.status)) {\n console.log(JSON.stringify(statusData, null, 2));\n break;\n }\n \n await new Promise((resolve) => setTimeout(resolve, 5000));\n}" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/fhir-push/upload": { "put": { "tags": [ "/api/v1/fhir-push" ], "summary": "Upload FHIR bundle to pre-signed URL", "description": "Upload your FHIR bundle JSON directly to the pre-signed URL obtained from GET /api/v1/fhir-push/upload-url. This is Step 2 of the CKG Data Ingestion workflow. The upload URL is a Google Cloud Storage pre-signed URL that expires after 15 minutes. Use HTTP PUT with the required headers to upload your FHIR bundle (max 500 MB). A 200 OK response confirms the upload was accepted. Any 4xx response indicates an issue such as an expired URL, invalid headers, or file size violation.", "parameters": [ { "name": "upload_url", "in": "query", "description": "The complete pre-signed upload URL returned from GET /api/v1/fhir-push/upload-url. This is a Google Cloud Storage URL, not a Suki API endpoint.", "required": true, "schema": { "type": "string", "example": "https://storage.googleapis.com/suki-fhir-push/..." } } ], "requestBody": { "required": true, "description": "Your FHIR bundle as raw JSON (not form-encoded, not base64-encoded).", "content": { "application/json": { "schema": { "type": "object", "description": "FHIR Bundle resource containing Patient, Encounter, Practitioner, and other clinical resources.", "example": { "resourceType": "Bundle", "type": "transaction", "entry": [ { "resource": { "resourceType": "Patient", "id": "patient-789", "name": [ { "family": "Doe", "given": [ "John" ] } ] } }, { "resource": { "resourceType": "Encounter", "id": "enc-123", "subject": { "reference": "Patient/patient-789" } } } ] } } } } }, "responses": { "200": { "description": "Upload successful. The FHIR bundle has been accepted and will be processed. Continue to Step 3 to poll ingestion status using the transaction_id from Step 1.", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request. Common causes: missing required headers (Content-Type or x-goog-content-length-range), file exceeds 500 MB size limit, or invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" } } } }, "403": { "description": "Forbidden. The upload URL has expired (15 minutes from creation). Request a new upload URL via GET /api/v1/fhir-push/upload-url and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "404": { "description": "Not found. The upload URL or target resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "410": { "description": "Gone. The upload URL is no longer valid. Request a new URL and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "# Upload URL obtained from Step 1\nUPLOAD_URL=\"\"\n\ncurl -X PUT \"$UPLOAD_URL\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-goog-content-length-range: 0,524288000\" \\\n --data-binary @my-fhir-bundle.json\n\n# 200 OK response indicates success" }, { "lang": "python", "label": "Python", "source": "import requests\n\nupload_url = \"\"\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-goog-content-length-range\": \"0,524288000\"\n}\n\nwith open(\"my-fhir-bundle.json\", \"rb\") as f:\n response = requests.put(\n upload_url,\n headers=headers,\n data=f,\n timeout=300 # 5 minutes for large files\n )\n\nresponse.raise_for_status()\nprint(f\"Upload successful: {response.status_code}\")" }, { "lang": "javascript", "label": "TypeScript", "source": "import fs from \"fs\";\n\nconst uploadUrl = \"\";\n\nconst bundleContent = fs.readFileSync(\"my-fhir-bundle.json\", \"utf-8\");\n\nconst response = await fetch(uploadUrl, {\n method: \"PUT\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-goog-content-length-range\": \"0,524288000\",\n },\n body: bundleContent,\n});\n\nif (!response.ok) {\n throw new Error(`Upload failed: ${response.status}`);\n}\n\nconsole.log(\"Upload successful\");" } ], "security": [] } }, "/api/v1/fhir-push/status/{transaction_id}": { "get": { "tags": [ "/api/v1/fhir-push" ], "summary": "Get FHIR Push transaction status", "description": "Poll the ingestion status for a FHIR bundle upload transaction. This is Step 3 of the CKG Data Ingestion workflow. Use the `transaction_id` returned from GET /api/v1/fhir-push/upload-url. Status values: CREATED (transaction created, awaiting upload), READY (bundle uploaded, queued for processing), RUNNING (actively ingesting), COMPLETED (successfully ingested into CKG), FAILED (processing error, see error field), ARCHIVED (upload not received within the allowed window). Poll at reasonable intervals (e.g., every 5 seconds) and stop once you receive a terminal status (COMPLETED, FAILED, or ARCHIVED). Transaction status is retained for 7 days after the last update.", "parameters": [ { "name": "transaction_id", "in": "path", "description": "Transaction identifier returned by `GET /api/v1/fhir-push/upload-url`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction status returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for this ingestion transaction." }, "organization_id": { "type": "string", "description": "Your partner organization ID for this organization. It can be a UUID or non-UUID string. But not a Suki UUID." }, "correlation_id": { "type": "string", "description": "Client-supplied or server-generated correlation ID for tracing." }, "status": { "type": "string", "description": "Current transaction status: CREATED | READY | RUNNING | COMPLETED | FAILED | ARCHIVED" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the transaction was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp of the last status update." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "RFC 3339 timestamp when processing completed (present for terminal statuses)." }, "error": { "type": "string", "nullable": true, "description": "Error details when the transaction status is FAILED; otherwise null." } }, "required": [ "transaction_id", "status", "created_at" ] }, "examples": { "completed": { "value": { "transaction_id": "dea454fe-fecb-4cf0-aaa7-fa84d19c28f8", "organization_id": "FHIR Push Medent Org 1", "correlation_id": "encounter-12345-upload-1", "status": "COMPLETED", "created_at": "2026-05-18T06:40:42Z", "updated_at": "2026-05-18T06:41:05Z", "completed_at": "2026-05-18T06:41:05Z", "error": null } } } } } }, "404": { "description": "Not Found. Unknown transaction_id or retention window exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.NotFoundError" } } } }, "401": { "description": "Unauthorized. Invalid or missing sdp_suki_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" } } } }, "403": { "description": "Forbidden. Token lacks required scopes or access to the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" } } } }, "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/fhir-push/status/ \\\n --header 'Authorization: Bearer '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get patient summary by encounter and practitioner", "description": "Returns the patient summary associated with the given encounter and practitioner. Suki maps the `fhir_encounter_id` and `fhir_practitioner_id` you provide to data previously ingested through CKG.", "parameters": [ { "name": "fhir_encounter_id", "in": "path", "description": "FHIR encounter identifier. Must match the encounter identifier in the ingested FHIR data.", "required": true, "schema": { "type": "string" } }, { "name": "fhir_practitioner_id", "in": "path", "description": "FHIR practitioner identifier. Must match the practitioner identifier in the ingested FHIR data.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "patient_summary": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "contents": { "type": "array", "items": { "type": "object", "properties": { "problem": { "type": "object", "properties": { "description": { "type": "string" } } }, "text": { "type": "string" }, "visit": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "description": { "type": "string" } } } } } }, "section_type": { "type": "string" }, "snippet_index": { "type": "integer" }, "title": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "value": { "patient_summary": { "sections": [ { "contents": [ { "problem": { "description": "Asthma" }, "text": "Patient presents with shortness of breath.", "visit": { "date": "2026-05-22T10:00:00Z", "description": "Follow-up for asthma" } } ], "section_type": "ABOUT_VISIT", "snippet_index": 0, "title": "About Visit" } ], "updated_at": "2026-05-22T10:00:00Z" } } } } } } }, "400": { "description": "Bad request. The request 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 encounter or practitioner does not exist, or no summary has been generated yet.", "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/patient-summary/encounter/enc-123/practitioner/pract-456 \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" }, { "lang": "python", "label": "Python", "source": "import requests\nimport json\n\nBASE_URL = \"https://sdp.suki.ai\"\nsdp_token = \"\"\nencounter_id = \"enc-123\"\npractitioner_id = \"pract-456\"\n\nurl = f\"{BASE_URL}/api/v1/patient-summary/encounter/{encounter_id}/practitioner/{practitioner_id}\"\nheaders = {\"sdp_suki_token\": sdp_token}\n\nresponse = requests.get(url, headers=headers, timeout=30)\nresponse.raise_for_status()\n\nsummary = response.json()\n\nprint(f\"Patient Summary: {summary['title']}\")\nprint(f\"Generated: {summary['generated_at']}\")\nprint(f\"\\nSections:\")\n\nfor section in summary.get(\"sections\", []):\n print(f\"\\n{section['heading']}:\")\n print(section['content'])" }, { "lang": "javascript", "label": "TypeScript", "source": "const BASE_URL = \"https://sdp.suki.ai\";\nconst sdpToken = \"\";\nconst encounterId = \"enc-123\";\nconst practitionerId = \"pract-456\";\n\nconst url = `${BASE_URL}/api/v1/patient-summary/encounter/${encounterId}/practitioner/${practitionerId}`;\n\nconst response = await fetch(url, {\n headers: { sdp_suki_token: sdpToken },\n});\n\nif (!response.ok) {\n throw new Error(`Failed to retrieve summary: ${response.status}`);\n}\n\nconst summary = await response.json();\n\nconsole.log(`Patient Summary: ${summary.title}`);\nconsole.log(`Generated: ${summary.generated_at}`);\nconsole.log(\"\\nSections:\");\n\nsummary.sections?.forEach((section: any) => {\n console.log(`\\n${section.heading}:`);\n console.log(section.content);\n});" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/pre_visit": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get pre-visit patient summary for encounter", "description": "Returns the pre-visit section from inside the full patient summary, created specifically for the user interface (UI) to display a preview to the provider.", "parameters": [ { "name": "fhir_encounter_id", "in": "path", "description": "FHIR encounter identifier.", "required": true, "schema": { "type": "string" } }, { "name": "fhir_practitioner_id", "in": "path", "description": "FHIR practitioner identifier.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pre_visit_summary": { "type": "object", "properties": { "last_visit": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "description": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "value": { "pre_visit_summary": { "last_visit": { "date": "2026-05-22T10:00:00Z", "description": "Follow-up for asthma" }, "updated_at": "2026-05-22T10:00:00Z" } } } } } } }, "400": { "description": "Bad request. The request 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 encounter or practitioner 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/patient-summary/encounter//practitioner//pre_visit \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/status": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get patient summary generation status for encounter", "description": "Returns the orchestration job status for the given FHIR encounter and practitioner identifiers (same format as sent via CKG ingestion). Common status values include READY, RUNNING, COMPLETED, FAILED, and ABORTED.", "parameters": [ { "name": "fhir_encounter_id", "in": "path", "description": "FHIR encounter identifier.", "required": true, "schema": { "type": "string" } }, { "name": "fhir_practitioner_id", "in": "path", "description": "FHIR practitioner identifier.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Orchestration job status.", "enum": [ "READY", "RUNNING", "COMPLETED", "FAILED", "ABORTED" ], "example": "RUNNING" } } } } } }, "400": { "description": "Bad request. The request 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 encounter or practitioner 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/patient-summary/encounter/enc-123/practitioner/pract-456/status \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/generate/encounter": { "post": { "tags": [ "/api/v1/patient-summary" ], "summary": "Generate patient summary for an encounter", "description": "Trigger asynchronous generation of a patient summary for a specific encounter and practitioner. The API returns 202 Accepted immediately when the job is scheduled. Generation typically completes within seconds to minutes depending on the volume of CKG data available. Poll GET /api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/status to check when generation completes, then retrieve the summary via the GET endpoint. Ensure FHIR data for the patient, encounter, and practitioner has been ingested via the CKG Data Ingestion API before triggering generation.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fhir_encounter_id": { "type": "string", "description": "FHIR encounter identifier (required)." }, "fhir_practitioner_id": { "type": "string", "description": "FHIR practitioner identifier (required)." } }, "required": [ "fhir_encounter_id", "fhir_practitioner_id" ] }, "example": { "fhir_encounter_id": "enc-123", "fhir_practitioner_id": "pract-456" } } } }, "responses": { "201": { "description": "Created. Summary generation request accepted and a patient summary resource was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "patient_summary_id": { "type": "string", "description": "Patient summary job ID returned from generate APIs." } }, "required": [ "patient_summary_id" ] }, "examples": { "created": { "value": { "patient_summary_id": "ee90d46e-1085-4a05-aa6a-1049113e857a" } } } } } }, "400": { "description": "Bad request. The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.BadRequestError" }, "examples": { "bad_request": { "value": { "code": 400, "message": "invalid request" } } } } } }, "401": { "description": "Unauthorized. The Suki access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.AuthenticationError" }, "examples": { "unauthorized": { "value": { "code": 401, "message": "invalid token" } } } } } }, "403": { "description": "Forbidden. Token lacks required scopes or access to the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.ForbiddenError" }, "examples": { "forbidden": { "value": { "code": 403, "message": "forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.InternalServerError" }, "examples": { "internal_error": { "value": { "code": 500, "message": "internal server error" } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url https://sdp.suki.ai/api/v1/patient-summary/generate/encounter \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\"fhir_encounter_id\":\"enc-123\",\"fhir_practitioner_id\":\"pract-456\"}'" }, { "lang": "python", "label": "Python", "source": "import requests\nimport time\n\nBASE_URL = \"https://sdp.suki.ai\"\nsdp_token = \"\"\nencounter_id = \"enc-123\"\npractitioner_id = \"pract-456\"\n\n# Step 1: Trigger generation\nresponse = requests.post(\n f\"{BASE_URL}/api/v1/patient-summary/generate/encounter\",\n headers={\"sdp_suki_token\": sdp_token, \"Content-Type\": \"application/json\"},\n json={\"fhir_encounter_id\": encounter_id, \"fhir_practitioner_id\": practitioner_id},\n timeout=30\n)\nresponse.raise_for_status()\nprint(f\"Generation triggered (Status: {response.status_code})\")\n\n# Step 2: Poll status until complete\nstatus_url = f\"{BASE_URL}/api/v1/patient-summary/encounter/{encounter_id}/practitioner/{practitioner_id}/status\"\nwhile True:\n status_resp = requests.get(status_url, headers={\"sdp_suki_token\": sdp_token}, timeout=30)\n status_data = status_resp.json()\n print(f\"Status: {status_data['status']}\")\n if status_data[\"status\"] == \"COMPLETED\":\n break\n elif status_data[\"status\"] == \"FAILED\":\n raise Exception(f\"Failed: {status_data.get('error')}\")\n time.sleep(5)\n\nprint(\"Generation completed successfully\")" }, { "lang": "javascript", "label": "TypeScript", "source": "const BASE_URL = \"https://sdp.suki.ai\";\nconst sdpToken = \"\";\nconst encounterId = \"enc-123\";\nconst practitionerId = \"pract-456\";\n\n// Step 1: Trigger generation\nconst generateResponse = await fetch(\n `${BASE_URL}/api/v1/patient-summary/generate/encounter`,\n {\n method: \"POST\",\n headers: {\n sdp_suki_token: sdpToken,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n fhir_encounter_id: encounterId,\n fhir_practitioner_id: practitionerId,\n }),\n }\n);\n\nif (!generateResponse.ok) {\n throw new Error(`Generation failed: ${generateResponse.status}`);\n}\n\nconsole.log(\"Generation triggered\");\n\n// Step 2: Poll status until complete\nconst statusUrl = `${BASE_URL}/api/v1/patient-summary/encounter/${encounterId}/practitioner/${practitionerId}/status`;\n\nwhile (true) {\n const statusResponse = await fetch(statusUrl, {\n headers: { sdp_suki_token: sdpToken },\n });\n const statusData = await statusResponse.json();\n \n console.log(`Status: ${statusData.status}`);\n \n if (statusData.status === \"COMPLETED\") {\n break;\n } else if (statusData.status === \"FAILED\") {\n throw new Error(`Failed: ${statusData.error}`);\n }\n \n await new Promise((resolve) => setTimeout(resolve, 5000));\n}\n\nconsole.log(\"Generation completed successfully\");" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/generate/provider-schedule": { "post": { "tags": [ "/api/v1/patient-summary" ], "summary": "Generate patient summaries for scheduled appointments", "description": "Trigger bulk asynchronous generation of patient summaries for all scheduled appointments on a provider's ingested schedule. Provide `fhir_practitioner_id` in the request body. This endpoint is optimized for pre-visit workflows where summaries need to be generated in advance before the provider's appointments begin. Returns 202 Accepted when the batch job is scheduled. Each appointment will have its own generation job that can be polled individually via the status endpoints. Use this to prepare summaries overnight or at the start of the day before the provider's appointments begin.", "parameters": [ { "$ref": "#/components/parameters/ProviderIdHeader" } ], "requestBody": { "required": true, "x-codegen-request-body-name": "body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.TriggerPatientSummaryGenerationRequest" }, "example": { "fhir_practitioner_id": "Practitioner/practitioner-1" } } } }, "responses": { "202": { "description": "Accepted. Generation scheduled." }, "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" } } } }, "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/patient-summary/generate/provider-schedule \\\n --header 'Content-Type: application/json' \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: ' \\\n --data '{\"fhir_practitioner_id\":\"Practitioner/practitioner-1\"}'" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/{patient_summary_id}": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get patient summary by ID", "description": "Retrieve a previously generated patient summary using its unique ID. Use this endpoint when you have the summary ID from a status response or previous retrieval. If you need to fetch a summary for a specific encounter and practitioner without knowing the summary ID, use GET /api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id} instead.", "parameters": [ { "name": "patient_summary_id", "in": "path", "description": "Patient summary identifier.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/controllers.PatientSummaryByIdResponse" }, "examples": { "success": { "value": { "patient_summary": { "sections": [ { "contents": [ { "problem": { "description": "Asthma" }, "text": "Patient presents with shortness of breath.", "visit": { "date": "2026-05-22T10:00:00Z", "description": "Follow-up for asthma" } } ], "section_type": "ABOUT_VISIT", "snippet_index": 0, "title": "About Visit" } ], "updated_at": "2026-05-22T10:00:00Z" } } } } } } }, "400": { "description": "Bad request. The request 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 patient summary 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/patient-summary/ \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/{patient_summary_id}/pre_visit": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get pre-visit summary by ID", "description": "Retrieve the exact pre-visit section from inside the full patient summary using the patient summary ID. This dedicated endpoint was created specifically for the user interface (UI) to display a preview to the provider.", "parameters": [ { "name": "patient_summary_id", "in": "path", "description": "Patient summary identifier.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pre_visit_summary": { "type": "object", "properties": { "last_visit": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "description": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "value": { "pre_visit_summary": { "last_visit": { "date": "2026-05-22T10:00:00Z", "description": "Follow-up for asthma" }, "updated_at": "2026-05-22T10:00:00Z" } } } } } } }, "400": { "description": "Bad request. The request 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 patient summary 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/patient-summary//pre_visit \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } }, "/api/v1/patient-summary/{patient_summary_id}/status": { "get": { "tags": [ "/api/v1/patient-summary" ], "summary": "Get summary generation status by ID", "description": "Returns the orchestration job status for the given patient summary ID. Common status values include READY, RUNNING, COMPLETED, FAILED, and ABORTED.", "parameters": [ { "name": "patient_summary_id", "in": "path", "description": "Patient summary identifier.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ProviderIdHeader" } ], "responses": { "200": { "description": "Success Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Orchestration job status.", "enum": [ "READY", "RUNNING", "COMPLETED", "FAILED", "ABORTED" ], "example": "RUNNING" } } } } } }, "400": { "description": "Bad request. The request 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 patient summary 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/patient-summary//status \\\n --header 'sdp_suki_token: ' \\\n --header 'sdp_provider_id: '" } ], "security": [ { "SukiTokenAuth": [] } ] } } }, "components": { "schemas": { "controllers.AuthenticationError": { "description": "Authentication Failure Response", "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "invalid token" } } }, "controllers.PatientSummary": { "type": "object", "description": "Comprehensive patient summary document with all relevant clinical information organized into sections. Generated from CKG data ingested via FHIR Push.", "required": [ "id", "patient_id", "generated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this patient summary document.", "example": "ps-abc123-def456" }, "patient_id": { "type": "string", "description": "FHIR Patient resource identifier from the ingested CKG data.", "example": "patient-789" }, "fhir_encounter_id": { "type": "string", "description": "FHIR Encounter resource identifier when summary is associated with a specific encounter.", "example": "enc-123" }, "fhir_practitioner_id": { "type": "string", "description": "FHIR Practitioner resource identifier when summary is scoped to a specific practitioner.", "example": "pract-456" }, "title": { "type": "string", "description": "Human-readable title for the patient summary.", "example": "Patient Summary for John Doe" }, "generated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the summary was generated.", "example": "2026-07-30T14:30:00Z" }, "sections": { "type": "array", "description": "Clinical information organized into logical sections (e.g., Medications, Allergies, Problems, Vitals).", "items": { "$ref": "#/components/schemas/controllers.PatientSummarySection" } } } }, "controllers.PatientSummarySection": { "type": "object", "description": "Individual section within a patient summary containing related clinical information.", "required": [ "heading", "content" ], "properties": { "heading": { "type": "string", "description": "Section heading (e.g., 'Medications', 'Allergies', 'Problems', 'Vitals').", "example": "Active Medications" }, "content": { "type": "string", "description": "Formatted clinical content for this section. May include markdown or plain text.", "example": "\u2022 Lisinopril 10mg daily\n\u2022 Metformin 500mg twice daily" }, "priority": { "type": "integer", "description": "Display priority for this section (lower numbers display first).", "example": 1 } } }, "controllers.PatientSummaryByIdResponse": { "type": "object", "description": "Success Response", "properties": { "patient_summary": { "$ref": "#/components/schemas/controllers.PatientSummaryDocument" } } }, "controllers.PatientSummaryDocument": { "type": "object", "description": "Comprehensive patient summary document with all relevant clinical information organized into sections.", "properties": { "sections": { "type": "array", "description": "Clinical information organized into logical sections.", "items": { "$ref": "#/components/schemas/controllers.PatientSummarySectionV2" } }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the patient summary was last updated.", "example": "2026-05-22T10:00:00Z" } } }, "controllers.PatientSummarySectionV2": { "type": "object", "description": "Individual section within a patient summary containing related clinical information.", "properties": { "contents": { "type": "array", "description": "Content items within this section, each representing a clinical snippet with optional problem and visit context.", "items": { "$ref": "#/components/schemas/controllers.PatientSummaryContentItem" } }, "section_type": { "type": "string", "description": "Type identifier for this section (e.g., ABOUT_VISIT).", "example": "ABOUT_VISIT" }, "snippet_index": { "type": "integer", "description": "Index of this snippet within the section.", "example": 0 }, "title": { "type": "string", "description": "Human-readable title for this section.", "example": "About Visit" } } }, "controllers.PatientSummaryContentItem": { "type": "object", "description": "A single content item within a patient summary section.", "properties": { "problem": { "$ref": "#/components/schemas/controllers.PatientSummaryProblem" }, "text": { "type": "string", "description": "Clinical text describing the content.", "example": "Patient presents with shortness of breath." }, "visit": { "$ref": "#/components/schemas/controllers.PatientSummaryVisit" } } }, "controllers.PatientSummaryProblem": { "type": "object", "description": "Problem or diagnosis associated with the content item.", "properties": { "description": { "type": "string", "description": "Description of the problem.", "example": "Asthma" } } }, "controllers.PatientSummaryVisit": { "type": "object", "description": "Visit details associated with the content item.", "properties": { "date": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp of the visit.", "example": "2026-05-22T10:00:00Z" }, "description": { "type": "string", "description": "Description of the visit.", "example": "Follow-up for asthma" } } }, "controllers.PatientSummaryPreVisit": { "type": "object", "description": "The pre-visit section from inside the full patient summary, created specifically for the user interface (UI) to display a preview to the provider.", "required": [ "id", "patient_id" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this pre-visit summary.", "example": "pvs-xyz789" }, "patient_id": { "type": "string", "description": "FHIR Patient resource identifier.", "example": "patient-789" }, "fhir_encounter_id": { "type": "string", "description": "FHIR Encounter identifier when associated with a specific appointment.", "example": "enc-123" }, "summary_snippet": { "type": "string", "description": "Brief one-line summary of key clinical information for quick review.", "example": "67yo M, HTN, DM2, due for A1C" }, "priority_sections": { "type": "array", "description": "Clinical information excerpts from the pre-visit section for review.", "items": { "$ref": "#/components/schemas/controllers.PreVisitSection" } }, "generated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the pre-visit summary was generated.", "example": "2026-07-30T14:30:00Z" } } }, "controllers.PreVisitSection": { "type": "object", "description": "An excerpt from a clinical section for pre-visit display.", "required": [ "heading", "excerpt" ], "properties": { "heading": { "type": "string", "description": "Section heading.", "example": "Chronic Conditions" }, "excerpt": { "type": "string", "description": "Content showing the most clinically relevant information in the pre-visit section.", "example": "Hypertension, Type 2 Diabetes" } } }, "controllers.PatientSummaryStatus": { "type": "object", "description": "Generation status for a patient summary job.", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "description": "Unique identifier for the summary generation job.", "example": "job-abc-123" }, "status": { "type": "string", "description": "Current status of the generation job.", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED" ], "example": "COMPLETED" }, "patient_summary_id": { "type": "string", "description": "ID of the generated summary (present when status is COMPLETED).", "example": "ps-def-456" }, "fhir_encounter_id": { "type": "string", "description": "Encounter ID for which the summary was generated.", "example": "enc-123" }, "fhir_practitioner_id": { "type": "string", "description": "Practitioner ID for whom the summary was generated.", "example": "pract-456" }, "created_at": { "type": "string", "format": "date-time", "description": "When the generation job was created.", "example": "2026-07-30T14:25:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp.", "example": "2026-07-30T14:30:00Z" }, "completed_at": { "type": "string", "format": "date-time", "description": "When the job completed (present for COMPLETED or FAILED status).", "nullable": true, "example": "2026-07-30T14:30:00Z" }, "error": { "type": "string", "description": "Error message if status is FAILED.", "nullable": true, "example": "Insufficient patient data for summary generation" } } }, "controllers.TriggerPatientSummaryGenerationRequest": { "type": "object", "description": "Request to trigger bulk asynchronous generation of patient summaries for all scheduled appointments on a provider's schedule.", "required": [ "fhir_practitioner_id" ], "properties": { "fhir_practitioner_id": { "type": "string", "description": "FHIR Practitioner resource identifier for whom to generate summaries.", "example": "Practitioner/practitioner-1" } }, "example": { "fhir_practitioner_id": "Practitioner/practitioner-1" } }, "controllers.FHIRPushUploadUrlResponse": { "type": "object", "description": "Response containing a pre-signed upload URL for FHIR bundle ingestion.", "required": [ "transaction_id", "upload_url", "expires_at" ], "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for this upload transaction. Use this to poll status.", "example": "dea454fe-fecb-4cf0-aaa7-fa84d19c28f8" }, "upload_url": { "type": "string", "description": "Pre-signed URL for uploading your FHIR bundle. Valid for 15 minutes. Use HTTP PUT with Content-Type: application/json.", "example": "https://storage.googleapis.com/suki-fhir-push/..." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the upload URL expires.", "example": "2026-07-30T14:45:42Z" }, "correlation_id": { "type": "string", "description": "Client-supplied correlation ID or server-generated value for tracking.", "example": "encounter-12345-upload-1" } } }, "controllers.FHIRPushStatusResponse": { "type": "object", "description": "Current processing status of a FHIR bundle upload transaction.", "required": [ "transaction_id", "status", "created_at" ], "properties": { "transaction_id": { "type": "string", "description": "Unique identifier for this transaction.", "example": "dea454fe-fecb-4cf0-aaa7-fa84d19c28f8" }, "organization_id": { "type": "string", "description": "Your partner organization ID for this organization. It can be a UUID or non-UUID string. But not a Suki UUID.", "example": "org-uuid-123" }, "correlation_id": { "type": "string", "description": "Client-supplied or server-generated correlation ID.", "example": "encounter-12345-upload-1" }, "status": { "type": "string", "description": "Current status: CREATED (awaiting upload), READY (uploaded, queued), RUNNING (processing), COMPLETED (success), FAILED (error), ARCHIVED (expired).", "enum": [ "CREATED", "READY", "RUNNING", "COMPLETED", "FAILED", "ARCHIVED" ], "example": "COMPLETED" }, "created_at": { "type": "string", "format": "date-time", "description": "When the transaction was created.", "example": "2026-07-30T14:30:42Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last status update timestamp.", "example": "2026-07-30T14:31:05Z" }, "completed_at": { "type": "string", "format": "date-time", "description": "When processing completed (present for terminal statuses).", "nullable": true, "example": "2026-07-30T14:31:05Z" }, "error": { "type": "string", "description": "Error details if status is FAILED.", "nullable": true, "example": null } } }, "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** for standard partners.\n\n**Required** for:\n\n- **Bearer authentication.** Send `provider_id` so Suki can identify the provider during Login or Register.\n- **Single Auth Token authentication.** Send `provider_id` so Suki can identify the clinician during Login or Register.", "example": "provider-123" } }, "description": "Partner credentials from onboarding. Bearer partners and Single Auth Token authentication 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": { "description": "Bad Request Response", "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "invalid request" } } }, "controllers.Code": { "type": "object", "properties": { "code": { "description": "Code value", "type": "string", "example": "30422" }, "description": { "description": "Description of the code", "type": "string", "example": "Essential hypertension" }, "type": { "type": "string", "enum": [ "UNSPECIFIED", "IMO", "ICD10", "SNOMED" ], "example": "IMO" } } }, "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": { "description": "The body of the content block usually refers to the content of the section.", "type": "string", "example": "Asthma exacerbation" }, "loinc_code": { "description": "The LOINC code of the content block.", "type": "string", "example": "18776-5" }, "source_transcripts": { "description": "The source transcripts that were used to generate the content block.", "type": "array", "items": { "type": "string" }, "example": [ "asthma", "exacerbation" ] }, "title": { "description": "The title of the content block usually refers to section name.", "type": "string", "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/concepts/ambient-clinical-notes/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", "description": "Session identifiers for Ambient session create. Pass `emr_encounter_id` for cross-modality interoperability and `encounter_id` to group re-ambient sessions for one note. If the first create omitted `encounter_id`, pass the returned `note_id` as the `encounter_id` value on later creates.", "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" }, "emr_encounter_id": { "type": "string", "maxLength": 36, "description": "**Optional for standalone sessions** - Visit interop key for interoperability. Accepts a UUID or non-UUID value, at most 36 characters. One EMR encounter can contain multiple notes. Required for cross-modality Ambient workflows.", "example": "123dfg-456dfg-789dfg-012dfg" }, "encounter_id": { "type": "string", "description": "**Optional** - Groups re-ambient sessions for one note. Pass it on the first session and reuse the same value on later creates. If the first create omitted it, pass the returned `note_id` as this field's value for re-ambient. There is no separate `note_id` request field. Up to 255 characters. Create does not return this field.", "example": "123dfg-456dfg-789dfg-012dfg" }, "multilingual": { "type": "boolean", "description": "**Deprecated.** Multilingual support is enabled by default for all Ambient sessions.", "example": false, "deprecated": true } } }, "controllers.CreateSessionResponse": { "type": "object", "description": "Identifiers returned after Ambient session create.", "properties": { "ambient_session_id": { "type": "string", "description": "UUID for the created Ambient session. Store this for later session API calls.", "example": "123dfg-456dfg-789dfg-012dfg" }, "note_id": { "type": "string", "description": "ID of the clinical note for this session. Use it as the `note_id` path parameter on note-level Ambient APIs (note content, note context, note structured data). If the first create omitted `encounter_id`, pass this value as the `encounter_id` field on later creates to re-ambient the same note.", "example": "123dfg-456dfg-789dfg-012dfg" }, "composition_id": { "type": "string", "deprecated": true, "description": "**Deprecated.** Same value as `note_id`. Kept for backward compatibility. Prefer `note_id`." } } }, "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": { "description": "list of diagnoses", "type": "array", "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": { "description": "Codes associated with the diagnosis", "type": "array", "items": { "$ref": "#/components/schemas/controllers.Code" } }, "diagnosis_note": { "description": "Diagnosis note", "type": "string", "example": "The management of essential hypertension remains unchanged from previous plans, as it was not the focus of today's visit." }, "laterality_indicator": { "description": "Laterality indicator", "type": "integer", "example": 4 }, "post_coord_lex_flag": { "description": "Post-coordination lexical flag", "type": "integer", "example": 1 } } }, "controllers.Dosage": { "type": "object", "properties": { "quantity": { "description": "(Optional) Dosage quantity", "type": "number", "example": 1 }, "raw_value": { "description": "(Optional) Raw dosage text", "type": "string", "example": "1 tablet" }, "unit": { "description": "(Optional) Dosage unit", "type": "string", "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": { "description": "(Optional) Raw medication form", "type": "string", "example": "Tablet" } } }, "controllers.Frequency": { "type": "object", "properties": { "raw_value": { "description": "(Optional) Raw frequency text", "type": "string", "example": "once daily" }, "structured_value": { "description": "(Optional) Frequency enum", "type": "string", "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": { "description": "Internal Server Error Response", "type": "object", "properties": { "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "internal server 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": { "description": "**Optional** - Diagnosis code value", "type": "string", "example": "I10" }, "type": { "description": "**Optional** - Diagnosis coding system", "type": "string", "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": { "description": "Not Found Response", "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "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** for standard partners.\n\n**Required** for:\n\n- **Bearer authentication.** Send `provider_id` so Suki can identify the provider during Login or Register.\n- **Single Auth Token authentication.** Send `provider_id` so Suki can identify the clinician during Login or Register.", "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": { "description": "(Optional) Raw administration route", "type": "string", "example": "Oral" } } }, "controllers.Strength": { "type": "object", "properties": { "raw_value": { "description": "(Optional) Raw strength value", "type": "string", "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/concepts/ambient-clinical-notes/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/concepts/ambient-clinical-notes/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" }, "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": { "description": "**Optional** - Medication code value", "type": "string", "example": "860975" }, "type": { "description": "**Optional** - Medication coding system", "type": "string", "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", "status" ], "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": "**Optional** - Standardized medication code (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": { "description": "Amount per administration", "allOf": [ { "$ref": "#/components/schemas/controllers.Dosage" } ] }, "drug_name": { "description": "Full medication name", "type": "string", "example": "Acetaminophen 500mg Tab" }, "duration_in_days": { "description": "Duration in days", "type": "integer", "example": 7 }, "end_date": { "description": "End date-time (RFC3339)", "type": "string", "example": "2026-01-08T00:00:00Z" }, "format": { "description": "Physical dosage form", "allOf": [ { "$ref": "#/components/schemas/controllers.Format" } ] }, "frequency": { "description": "Administration frequency", "allOf": [ { "$ref": "#/components/schemas/controllers.Frequency" } ] }, "instructions": { "description": "Free-form instructions", "type": "string", "example": "Take with food" }, "linked_diagnosis_codes": { "description": "Linked ICD10 diagnosis codes", "type": "array", "items": { "$ref": "#/components/schemas/controllers.LinkedDiagnosisCode" } }, "medication_code": { "description": "Standardized medication code", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationCode" } ] }, "medication_timing": { "description": "Timing modifiers", "allOf": [ { "$ref": "#/components/schemas/controllers.MedicationTiming" } ] }, "number_of_refills": { "description": "Number of refills", "type": "integer", "example": 3 }, "quantity_dispensed": { "description": "Quantity dispensed", "type": "string", "example": "1 box" }, "route": { "description": "Administration route", "allOf": [ { "$ref": "#/components/schemas/controllers.Route" } ] }, "start_date": { "description": "Start date-time (RFC3339)", "type": "string", "example": "2026-01-01T00:00:00Z" }, "status": { "description": "Order status", "type": "string", "enum": [ "ACTIVE", "DISCONTINUED", "REFILLED" ], "example": "ACTIVE" }, "strength": { "description": "Medication strength/concentration", "allOf": [ { "$ref": "#/components/schemas/controllers.Strength" } ] } } }, "controllers.MedicationOrders": { "type": "object", "properties": { "partial_values": { "description": "Medication Orders that are not submittable (Criteria decided based on target_emr provided in EmrContext)", "type": "array", "items": { "$ref": "#/components/schemas/controllers.MedicationOrderResponse" } }, "values": { "description": "Emr Submittable medication Orders (Criteria decided based on target_emr provided in EmrContext)", "type": "array", "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": { "description": "(Optional) Raw timing text", "type": "string", "example": "morning" }, "structured_value": { "description": "(Optional) Medication timing enum", "type": "string", "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": { "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. Response shape is the same for static, dynamic, and mixed sessions; field population differs by entry type.", "type": "object", "properties": { "structured_data": { "$ref": "#/components/schemas/controllers.FormFillingStructuredData" } } }, "controllers.FormFillingStructuredData": { "description": "Medical form instances for a form-filling session. `generated_values` can include static template instances and dynamic schema instances from the same session.", "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 form instance for a form-filling session. Static (template) and dynamic (schema) entries share this shape; some fields differ by source.", "type": "object", "properties": { "correlation_id": { "type": "string", "example": "20965414-929a-4f71-a3e5-b92bec07d086", "description": "Session group / correlation identifier for the form-filling session." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z", "description": "When the form instance was created." }, "data": { "type": "object", "additionalProperties": true, "example": {}, "description": "Filled JSON field values for this form instance." }, "form_template_id": { "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0-template", "description": "Suki Medical form template ID for static entries. Typically empty for dynamic schema entries." }, "id": { "type": "string", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0", "description": "Form instance ID. For static templates, a Suki medical form UUID. For dynamic forms, the partner `id` from context when provided; otherwise a Suki dynamic form UUID." }, "metadata": { "type": "object", "additionalProperties": true, "example": {}, "description": "Optional free-form metadata object." }, "patient_id": { "type": "string", "example": "patient-123", "description": "Patient identifier when available from ambient or stored form context." }, "status": { "type": "string", "example": "MEDICAL_FORM_STATUS_COMPLETED", "description": "Lifecycle status for static medical forms (for example MEDICAL_FORM_STATUS_COMPLETED). Typically empty for dynamic forms." }, "title": { "type": "string", "example": "Adult Vitals", "description": "Display title. From the template for static entries; from context `name` for dynamic entries when provided." }, "type": { "type": "string", "example": "VITALS_ASSESSMENT", "description": "Medical form type. From the template or instance for static entries; from context `type` for dynamic entries when provided." } } }, "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": "Form list for the Form filling session.", "required": [ "values" ], "properties": { "values": { "description": "Forms to fill in this session. Include at least one entry. Each entry is either a Suki template or a partner schema. You can mix both types in the same list.", "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/controllers.FormFillingMetadata" } } } }, "controllers.FormFillingMetadata": { "description": "One form to fill. Send either `form_template_id` or `schema`. Do not send both, and do not leave both empty.", "oneOf": [ { "title": "Static template", "type": "object", "required": [ "form_template_id" ], "additionalProperties": false, "properties": { "form_template_id": { "description": "Suki Medical form template ID. Get this from `GET /api/v1/info/suki-medical-form-templates`.", "type": "string", "format": "uuid", "example": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" } } }, { "title": "Dynamic schema", "type": "object", "required": [ "schema" ], "additionalProperties": false, "properties": { "schema": { "description": "Partner-defined form fields to fill. Use this when the form is not a Suki template.", "type": "object", "additionalProperties": true, "example": { "title": "Wound Check", "type": "object", "properties": { "wound_status": { "type": "string" } } } }, "id": { "description": "Optional partner ID for this form. If set, structured data returns it as `generated_values[].id`.", "type": "string", "example": "partner-wound-1" }, "name": { "description": "Optional display name for this form. If set, structured data returns it as `generated_values[].title`.", "type": "string", "example": "Wound Check" }, "type": { "description": "Optional form type name, such as `VITALS_ASSESSMENT`. Use the enum name, not a number. If omitted, Suki treats it as `FORM_TYPE_UNSPECIFIED`.", "type": "string", "enum": [ "FORM_TYPE_UNSPECIFIED", "SKIN_ASSESSMENT", "NEURO_ASSESSMENT", "VITALS_ASSESSMENT", "RESPIRATORY_ASSESSMENT", "GENITO_URINARY_ASSESSMENT", "GASTRO_INTESTINAL_ASSESSMENT", "CARDIAC_ASSESSMENT", "MSK_ASSESSMENT", "IO_ASSESSMENT", "PAIN_ASSESSMENT", "NIHSS_ASSESSMENT", "BRADEN_ASSESSMENT", "HRA_ASSESSMENT", "LDA_GROUP", "ROVER_NURSING_SCHEMA_LOAD" ], "example": "VITALS_ASSESSMENT" } } } ] }, "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", "description": "Session context for Form filling. To enable form filling, include at least one entry in `form_filling.values`; each entry MUST include either `form_template_id` or `schema`. Seeding is required to generate filled forms.", "properties": { "form_filling": { "description": "Forms to fill for this session. Required only when you send context.", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingContext" } ] } } }, "controllers.FormFillingUpdateContextRequest": { "type": "object", "description": "Partial update for Form filling session context. Send only the fields you want to change.", "properties": { "form_filling": { "description": "Updated forms to fill for this session.", "allOf": [ { "$ref": "#/components/schemas/controllers.FormFillingContext" } ] } } }, "controllers.EncounterNote": { "description": "A single note (composition) for an EMR encounter.", "type": "object", "properties": { "created_at": { "description": "Note creation time (RFC3339).", "type": "string", "example": "2026-01-01T00:00:00Z" }, "id": { "type": "string", "example": "123dfg-456dfg-789dfg-012dfg" }, "status": { "description": "Note status. Currently, the only valid value is DEFAULT.", "type": "string", "example": "DEFAULT" }, "updated_at": { "description": "Note last-update time (RFC3339); unset for signed NOTEs (immutable).", "type": "string", "example": "2026-01-01T00:00:00Z" } } }, "controllers.GetNoteContentResponse": { "description": "Accumulated note content across sessions in the note. For sections that were edited (for example in Web SDK), returns the latest edited section content.", "type": "object", "properties": { "summary": { "description": "Summary of the note (section content blocks rendered from the composition).", "type": "array", "items": { "$ref": "#/components/schemas/controllers.ContentBlock" } } } }, "controllers.GetNoteContextResponse": { "description": "Visit context aggregated across sessions in the note.", "type": "object", "properties": { "context": { "description": "Note-level ambient context.", "allOf": [ { "$ref": "#/components/schemas/controllers.NoteContext" } ] } } }, "controllers.GetNoteStructuredDataResponse": { "description": "Accumulated diagnoses and orders across sessions in the note.", "type": "object", "properties": { "structured_data": { "description": "Structured data (diagnoses, orders) sourced from the composition.", "allOf": [ { "$ref": "#/components/schemas/controllers.StructuredData" } ] } } }, "controllers.ListEncounterNotesResponse": { "description": "Notes linked to the EMR encounter.", "type": "object", "properties": { "notes": { "description": "All notes (compositions) for the EMR encounter.", "type": "array", "items": { "$ref": "#/components/schemas/controllers.EncounterNote" } } } }, "controllers.GetEncounterInfoResponse": { "description": "Resolved note → session hierarchy for an EMR encounter.", "type": "object", "properties": { "notes": { "description": "Notes with sessions and artifact availability for the EMR encounter.", "type": "array", "items": { "$ref": "#/components/schemas/controllers.EncounterInfoNote" } } } }, "controllers.EncounterInfoNote": { "description": "Note metadata and related sessions for an encounter.", "type": "object", "properties": { "note_id": { "type": "string", "description": "Note identifier (use with note-level APIs)." }, "created_at": { "type": "string", "format": "date-time", "description": "Note creation time (RFC3339)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Note last-update time (RFC3339); unset for signed notes (immutable)." }, "sessions": { "type": "array", "description": "Sessions associated with this note.", "items": { "$ref": "#/components/schemas/controllers.EncounterInfoSession" } } } }, "controllers.EncounterInfoSession": { "description": "Session identifier, status, and available artifacts.", "type": "object", "properties": { "session_id": { "type": "string", "description": "Ambient session ID (job owner identifier)." }, "status": { "type": "string", "description": "job.Status enum name (for example \"COMPLETED\")." }, "artifacts": { "type": "array", "items": { "type": "string" }, "description": "Available session artifacts. Allowed values (v1): \"transcript\", \"recording\", \"content\". Omitted when unavailable." } } }, "controllers.NoteContext": { "description": "Aggregated visit context for the note.", "type": "object", "properties": { "chief_complaint": { "type": "string", "example": "Headache", "description": "Chief complaint. Maximum 255 characters." }, "encounter_type": { "type": "string", "example": "AMBULATORY", "description": "Encounter type aggregated across sessions in the note." }, "provider_role": { "type": "string", "example": "ATTENDING", "description": "Provider role aggregated across sessions in the note." }, "reason_for_visit": { "type": "string", "example": "Follow-up for migraines", "description": "Reason for visit. Maximum 255 characters." }, "visit_type": { "type": "string", "example": "ESTABLISHED_PATIENT", "description": "Visit type aggregated across sessions in the note." } } }, "controllers.MedicalFormType": { "description": "Medical form type enum name for form-filling context entries. Use the string name, not a numeric value.", "type": "string", "enum": [ "FORM_TYPE_UNSPECIFIED", "SKIN_ASSESSMENT", "NEURO_ASSESSMENT", "VITALS_ASSESSMENT", "RESPIRATORY_ASSESSMENT", "GENITO_URINARY_ASSESSMENT", "GASTRO_INTESTINAL_ASSESSMENT", "CARDIAC_ASSESSMENT", "MSK_ASSESSMENT", "IO_ASSESSMENT", "PAIN_ASSESSMENT", "NIHSS_ASSESSMENT", "BRADEN_ASSESSMENT", "HRA_ASSESSMENT", "LDA_GROUP", "ROVER_NURSING_SCHEMA_LOAD" ], "example": "VITALS_ASSESSMENT" } }, "securitySchemes": { "SukiTokenAuth": { "type": "apiKey", "in": "header", "name": "sdp_suki_token", "description": "Suki access token (`suki_token`) from Login or Register. Expires after one hour." } }, "parameters": { "ProviderIdHeader": { "name": "sdp_provider_id", "in": "header", "description": "**Optional** for standard partners.\n\n**Required** for:\n\n- **Bearer authentication.** Use the same `provider_id` returned by the Login or Register API.\n- **Single Auth Token authentication.** Include the same `provider_id` on every request as `sdp_provider_id`.", "required": false, "schema": { "type": "string", "example": "provider-123" } } } }, "security": [ { "SukiTokenAuth": [] } ] }