{ "openapi": "3.0.3", "info": { "title": "Core Server API", "description": "Reference for the server-side Core API.", "version": "1.0.0" }, "servers": [ { "url": "https://{region}.api.nabla.com/v1/core/server", "variables": { "region": { "enum": [ "us", "eu" ], "default": "us", "description": "Geographical region where your Nabla Core API organization exists." } } } ], "security": [ { "bearer": [] } ], "paths": { "/oauth/token": { "post": { "summary": "Authenticate your backend", "description": "Use this endpoint to get a medium-lived JWT access token for your backend to perform calls the Server API exposed by Nabla. See the [Authentication](/next/guides/authentication) guide for details on how to construct the client assertion.", "tags": [ "Authentication" ], "operationId": "oauth-generate-server-access-token", "x-unauthenticated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "This endpoint only supports the 'client_credentials' value.", "example": "client_credentials" }, "client_assertion_type": { "type": "string", "description": "This endpoint only supports the 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' value.", "example": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" }, "client_assertion": { "type": "string", "description": "A short-lived JWT assertion that serves to authenticate this request." } }, "required": [ "grant_type", "client_assertion_type", "client_assertion" ] } } } }, "responses": { "200": { "description": "A JWT access token that can be used to access the server API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "$ref": "#/components/schemas/jwt_token" }, "expires_in": { "type": "integer", "description": "The lifetime of the access token, in seconds." } }, "required": [ "access_token", "expires_in" ] } } } } } } }, "/transcribe": { "post": { "summary": "Transcribe — From audio file", "description": "Generate a transcript from an audio file. Only `audio/*` mime types are supported. The maximum duration is 10 minutes. If you have longer files, please use the [asynchronous equivalent](/next/server/transcribe-async).", "tags": [ "Transcribe" ], "operationId": "transcribe", "x-custom-timeout-seconds": 300, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "request_parameters": { "$ref": "#/components/schemas/transcribe_request" }, "file": { "type": "string", "format": "binary" } }, "required": [ "request_parameters", "file" ] } } } }, "responses": { "200": { "description": "Results of processing the audio file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transcribe_response" } } } } } } }, "/transcribe-async": { "post": { "summary": "Transcribe — From audio file asynchronously", "description": "Generate a transcript from an audio file. Only `audio/*` mime types are supported. The maximum duration is 60 minutes.", "tags": [ "Transcribe" ], "operationId": "transcribe-async", "x-custom-async-timeout-seconds": 1800, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transcribe_async_request" } } } }, "responses": { "200": { "description": "Request received and processing started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_transcription" } } } } } } }, "/transcribe-async/{id}": { "parameters": [ { "$ref": "#/components/parameters/async_request_id" } ], "get": { "summary": "Get an asynchronous transcription", "description": "Poll the status —and results if successful— of an asynchronous transcription.", "operationId": "get-transcribe-async", "x-multi-wired-handler": true, "responses": { "200": { "description": "The asynchronous transcription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_transcription" } } } } } } }, "/dictate": { "post": { "summary": "Dictate — From audio file", "description": "Generate a dictation from an audio file. Only `audio/*` mime types are supported. The maximum duration is 10 minutes. If you have longer files, please use the [asynchronous equivalent](/next/server/dictate-async).", "tags": [ "Dictate" ], "operationId": "dictate", "x-custom-timeout-seconds": 300, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "request_parameters": { "$ref": "#/components/schemas/dictate_request" }, "file": { "type": "string", "format": "binary" } }, "required": [ "request_parameters", "file" ] } } } }, "responses": { "200": { "description": "Results of processing the audio file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dictate_response" } } } } } } }, "/dictate-async": { "post": { "summary": "Dictate — From audio file asynchronously", "description": "Generate a dictation from an audio file. Only `audio/*` mime types are supported. The maximum duration is 60 minutes.", "tags": [ "Dictate" ], "operationId": "dictate-async", "x-custom-async-timeout-seconds": 1800, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dictate_async_request" } } } }, "responses": { "200": { "description": "Request received and processing started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_dictation" } } } } } } }, "/dictate-async/{id}": { "parameters": [ { "$ref": "#/components/parameters/async_request_id" } ], "get": { "summary": "Get an asynchronous dictation", "description": "Poll the status —and results if successful— of an asynchronous dictation.", "operationId": "get-dictation-async", "x-multi-wired-handler": true, "responses": { "200": { "description": "The asynchronous dictation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_dictation" } } } } } } }, "/generate-note": { "post": { "summary": "Generate a note", "description": "Generate a structured clinical note given the transcript.", "tags": [ "Digest" ], "operationId": "generate-note", "x-custom-timeout-seconds": 600, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_note_request" } } } }, "responses": { "200": { "description": "The generated note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_note_response" } } } } } } }, "/generate-note-async": { "post": { "summary": "Generate a note asynchronously", "description": "Creates an asynchronous task (also called asynchronous request) that will generate a structured clinical note given the transcript, then keeps the response for two hours before removing it, allowing it to be fetched using the [poll endpoint](/next/server/get-generate-note-async).\nMore details about asynchronous note generation can be found in the [best practices guide](/next/guides/best-practices/asynchronous-note-generation).", "tags": [ "Digest" ], "operationId": "generate-note-async", "x-custom-async-timeout-seconds": 600, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_note_async_request" } } } }, "responses": { "200": { "description": "Request received and processing started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_note_generation" } } } } } } }, "/generate-note-async/{id}": { "parameters": [ { "$ref": "#/components/parameters/async_request_id" } ], "get": { "summary": "Get an asynchronous note generation", "description": "Poll the status —and results if successful— of an asynchronous note generation.", "operationId": "get-generate-note-async", "x-multi-wired-handler": true, "responses": { "200": { "description": "The asynchronous note generation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/async_note_generation" } } } } } } }, "/generate-normalized-data": { "post": { "summary": "Generate normalized data from a note", "description": "Generate normalized data from a Nabla-generated clinical note by extracting ICD-10 and LOINC codes in a FHIR-compliant structure.\n\nIt adeptly identifies and categorizes key medical information within the notes, such as past medical history, family medical history, clinical assessments, and vital signs.\n\nEach piece of medical information is represented as an array of FHIR's conditions/observations, each including relevant ICD-10 codes, thereby ensuring compatibility with standardized medical data frameworks.\n\nThe Normalize functionality is tailored to enhance the integration of clinical notes into Electronic Health Records (EHRs), facilitating accurate and efficient documentation by aligning with FHIR protocols.", "tags": [ "Normalize" ], "operationId": "generate-normalized-data", "x-custom-timeout-seconds": 600, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_normalized_data_request" } } } }, "responses": { "200": { "description": "The normalized data extracted from the note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/normalized_data" } } } } } } }, "/generate-patient-instructions": { "post": { "summary": "Generate patient instructions", "description": "Generates clear, post-visit instructions based on what the healthcare provider communicated to the patient during the encounter. These instructions are intended to help patients better understand and follow their care plan.\n\n:::note Provider review\n\nPatient instructions are generated automatically and may be translated. A licensed healthcare provider should review and approve them before sharing with the patient, especially when translation is involved.\n\n:::\n\nThis endpoint supports multiple input formats and languages to fit a variety of clinical workflows.", "tags": [ "Patient Instructions" ], "operationId": "generate-patient-instructions", "x-custom-timeout-seconds": 600, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_patient_instructions_request" } } } }, "responses": { "200": { "description": "Patient instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generate_patient_instructions_response" } } } } } } }, "/edit-note-with-instructions": { "post": { "summary": "Edit Note With Instructions", "description": "Edit the Nabla-generated clinical note following human-readable text instructions, to customize and have more control over its content and structure.", "tags": [ "Edit Note With Instructions" ], "operationId": "edit-note-with-instructions", "x-custom-timeout-seconds": 600, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/edit_note_with_instructions_request" } } } }, "responses": { "200": { "description": "Patient instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/edit_note_with_instructions_response" } } } } } } }, "/reports": { "post": { "summary": "Create report", "description": "Create detailed feedback or report issues directly related to specific API interactions.", "tags": [ "Report" ], "operationId": "create-report", "x-custom-timeout-seconds": 150, "x-multi-wired-handler": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_report_request" } } } }, "responses": { "200": { "description": "The created report id, to be referenced when emailing support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } } }, "/users": { "post": { "summary": "Create a user", "description": "Creates a Core API user.", "tags": [ "Manage users" ], "operationId": "create-user", "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": {}, "properties": { "external_id": { "type": "string", "description": "A unique identifier for the user from another system which is given to Nabla.", "nullable": true, "maxLength": 256 }, "metadata": { "$ref": "#/components/schemas/metadata" } } } } } } }, "get": { "summary": "Get users", "description": "Retrieve a list of your organization's Core API Users, ordered by creation time.", "tags": [ "Manage users" ], "operationId": "get-users", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/order" }, { "name": "activated", "description": "Optional filter for activated/deactivated users.", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A paginated list of Users.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "has_more": { "type": "boolean", "example": true }, "next_cursor": { "$ref": "#/components/schemas/next_cursor" } }, "required": [ "data", "has_more" ] } } } } } } }, "/users/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "get": { "summary": "Get a user", "description": "Get a single user by their id.", "tags": [ "Manage users" ], "operationId": "get-user", "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } } }, "patch": { "summary": "Update a user", "description": "Update a Nabla Core API user. Please be aware that this operation supports partial updates of the user's fields. However partial updates are not supported within the metadata dictionary. Therefore, to update a field within metadata, you must resend the entire dictionary each time.", "tags": [ "Manage users" ], "operationId": "update-user", "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-patch-properties": [ "external_id", "metadata" ], "properties": { "external_id": { "type": "string", "description": "A unique identifier for the user from another system which is given to Nabla.", "nullable": true, "maxLength": 256 }, "metadata": { "$ref": "#/components/schemas/metadata" } } } } } } } }, "/users/find_by_external_id/{external_id}": { "parameters": [ { "in": "path", "name": "external_id", "description": "A unique identifier for the user from another system.", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Find a user by their external id", "description": "Get a single user by their external id.", "tags": [ "Manage users" ], "operationId": "find-user-by-external-id", "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } } } }, "/users/{user_id}/activate": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Activate a user", "description": "Re-activate a previously [deactivated](/next/server/deactivate-user) user.", "tags": [ "Manage users" ], "operationId": "activate-user", "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/users/{user_id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Deactivate a user", "description": "Deactivate a user. Deactivated users loose access to the API. They will face authentication errors and will not be able to use any feature.", "operationId": "deactivate-user", "tags": [ "Manage users" ], "responses": { "200": { "description": "User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/jwt/authenticate/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "post": { "summary": "Authenticate a user", "description": "Use this endpoint to get JWT tokens to authenticate a user with the Nabla Core API. These tokens only gives access to resources for the specified user. This endpoint should typically be called by your backend on behalf of an authenticated user, and the resulting JWT tokens should be forwarded to the user's frontend securely.", "tags": [ "Authentication" ], "operationId": "jwt-authenticate-user", "responses": { "200": { "description": "Tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/session_tokens" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "ws_error_message": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ERROR_MESSAGE" ] }, "message": { "type": "string", "description": "A human-readable explanation of the error, often including contextual details to help understand what went wrong." }, "code": { "type": "integer", "description": "A numeric identifier for the error. This may either be a standard HTTP status code (e.g. 400, 401) or a more specific application-level code (typically >1000). Some errors —like an audio buffer overflow due to client misuse— have dedicated codes, while others —like malformed JSON— use broader and generic codes.\n\n**Tip**: You should use this field as the primary reference for implementing error handling logic." }, "name": { "type": "string", "description": "An internal enum-style name associated with the error code. While it may help with debugging, it’s mainly for reference—always rely on the numeric code for programmatic handling." }, "trace_id": { "type": "string", "description": "A unique identifier for the failed API request. This is especially useful when reaching out to Nabla support, as it allows us to trace the exact request in our systems." } }, "required": [ "type", "message", "code", "name" ], "example": [ { "type": "ERROR_MESSAGE", "message": "Unable to parse JSON at path $.speech_locales", "code": 400, "name": "BAD_REQUEST", "trace_id": "projects/xxxxx/traces/abcd123456789xyz" }, { "type": "ERROR_MESSAGE", "message": "Received a huge amount of audio in a very short window time.", "code": 83016, "name": "AUDIO_CHUNKS_BUFFER_OVERFLOW", "trace_id": "projects/xxxxx/traces/abcd123456789xyz" } ] }, "transcribe_config": { "type": "object", "description": "First message to configure transcription (audio format, locale, etc).", "properties": { "type": { "type": "string", "enum": [ "CONFIG" ] }, "streams": { "type": "array", "description": "Describe the audio streams you intend to stream as input of the Transcribe API. Typically, if you have separate doctor/patient audio tracks (or do diarization yourself) you will configure two streams for transcription. Remember that a stream will expect audio to flow continuously, otherwise a timeout error will be thrown.", "items": { "$ref": "#/components/schemas/transcribe_config_stream" } }, "encoding": { "$ref": "#/components/schemas/audio_encoding" }, "sample_rate": { "type": "integer", "description": "Sample rate of submitted streaming audio, in hertz.", "minimum": 8000, "maximum": 192000, "example": 16000 }, "speech_locales": { "$ref": "#/components/schemas/speech_locale_array", "description": "An array of up to two locales for transcription. The speech-to-text engine automatically detects the spoken locale from this list. Each `transcript_item` received in the websocket will then specify the detected locale, enabling accurate transcription of **bilingual encounters**." }, "split_by_sentence": { "type": "boolean", "default": false, "description": "Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio." }, "enable_audio_chunk_ack": { "type": "boolean", "default": false, "description": "If enabled, audio chunks should contain a `seq_id`, and the server will periodically send acknowledgements up to the specified `seq_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "streams", "encoding", "sample_rate", "speech_locales" ], "example": { "type": "CONFIG", "encoding": "PCM_S16LE", "sample_rate": 16000, "speech_locales": [ "ENGLISH_US", "SPANISH_ES" ], "streams": [ { "id": "DOCTOR_STREAM", "speaker_type": "DOCTOR" }, { "id": "PATIENT_STREAM", "speaker_type": "PATIENT" } ], "split_by_sentence": true } }, "transcribe_audio_chunk": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK" ] }, "payload": { "type": "string", "description": "Raw audio chunk in base64 string.", "example": "ZXhhbXBsZQ==" }, "stream_id": { "type": "string", "description": "Identifier of one of the streams you defined in `streams` in the configuration.", "example": "doctor_stream" }, "seq_id": { "type": "integer", "description": "A unique identifier for this audio chunk within its stream, expected to be sequential (n+1) from one audio chunk to the next.\nFirst value (i.e. for the first audio chunk of a stream) can start at any arbitrary value.\nThis field is required if you enabled the audio chunk acknowledgement protocol in the configuration.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "payload", "stream_id" ] }, "transcribe_end": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "END" ] } }, "required": [ "type" ], "example": { "type": "END" } }, "transcribe_output": { "oneOf": [ { "$ref": "#/components/schemas/transcribe_transcript_item" }, { "$ref": "#/components/schemas/transcribe_audio_chunk_ack" }, { "$ref": "#/components/schemas/ws_error_message" } ], "discriminator": { "propertyName": "type", "mapping": { "transcript_item": "#/components/schemas/transcribe_transcript_item", "audio_chunk_ack": "#/components/schemas/transcribe_audio_chunk_ack", "error_message": "#/components/schemas/ws_error_message" } } }, "transcribe_output_v2": { "oneOf": [ { "$ref": "#/components/schemas/transcribe_transcript_item" }, { "$ref": "#/components/schemas/transcribe_audio_chunk_ack" }, { "$ref": "#/components/schemas/ws_error_message" } ], "discriminator": { "propertyName": "type", "mapping": { "TRANSCRIPT_ITEM": "#/components/schemas/transcribe_transcript_item", "AUDIO_CHUNK_ACK": "#/components/schemas/transcribe_audio_chunk_ack", "ERROR_MESSAGE": "#/components/schemas/ws_error_message" } } }, "transcribe_audio_chunk_ack": { "type": "object", "description": "Acknowledgement of audio receipt by the server up to the audio chunk with the sequential id `ack_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience).", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK_ACK" ] }, "stream_id": { "type": "string", "description": "ID of the stream to which the ack-ed chunk belongs." }, "ack_id": { "type": "integer", "description": "The sequential id of the audio chunk up to which this acknowledgment applies." } }, "example": { "type": "AUDIO_CHUNK_ACK", "stream_id": "patient_stream", "ack_id": 42 }, "required": [ "type", "ack_id", "stream_id" ] }, "listen_config": { "type": "object", "description": "First message to configure transcription (audio format, language, etc).", "properties": { "object": { "type": "string", "enum": [ "listen_config" ] }, "output_objects": { "type": "array", "items": { "type": "string", "description": "Specifies which items you want us to send you back. Currently only transcription (i.e. `transcript_item`) is supported.", "enum": [ "transcript_item" ], "example": "transcript_item" } }, "streams": { "type": "array", "description": "Describe the audio streams you intend to stream as input of the Listen API. Typically, if you have separate doctor/patient audio tracks (or do diarization yourself) you will configure two streams for transcription. Remember that a stream will expect audio to flow continuously, otherwise a timeout error will be thrown.", "items": { "$ref": "#/components/schemas/listen_config_stream" } }, "encoding": { "$ref": "#/components/schemas/old_audio_encoding" }, "sample_rate": { "type": "integer", "description": "Sample rate of submitted streaming audio, in hertz.", "example": 16000 }, "language": { "$ref": "#/components/schemas/legacy_language", "description": "Language spoken in the audio ('en' and 'fr' are still supported but deprecated, and respectively equivalent to 'en-US' and 'fr-FR')." }, "split_by_sentence": { "type": "boolean", "default": false, "description": "Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio." }, "enable_audio_chunk_ack": { "type": "boolean", "default": false, "description": "If enabled, audio chunks should contain a `seq_id`, and the server will periodically send acknowledgements up to the specified `seq_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "object", "output_objects", "streams", "encoding", "sample_rate", "language" ], "example": { "object": "listen_config", "output_objects": [ "transcript_item" ], "encoding": "pcm_s16le", "sample_rate": 16000, "language": "en-US", "streams": [ { "id": "doctor_stream", "speaker_type": "doctor" }, { "id": "patient_stream", "speaker_type": "patient" } ], "split_by_sentence": true } }, "listen_audio_chunk": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "audio_chunk" ] }, "payload": { "type": "string", "description": "Raw audio chunk in base64 string.", "example": "ZXhhbXBsZQ==" }, "stream_id": { "type": "string", "description": "Identifier of one of the streams you defined in `streams` in the configuration.", "example": "doctor_stream" }, "seq_id": { "type": "integer", "description": "A unique identifier for this audio chunk within its stream, expected to be sequential (n+1) from one audio chunk to the next.\nFirst value (i.e. for the first audio chunk of a stream) can start at any arbitrary value.\nThis field is required if you enabled the audio chunk acknowledgement protocol in the configuration.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "object", "payload", "stream_id" ] }, "listen_end": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "end" ] } }, "required": [ "object" ], "example": { "object": "end" } }, "listen_output": { "oneOf": [ { "$ref": "#/components/schemas/listen_transcript_item" }, { "$ref": "#/components/schemas/listen_audio_chunk_ack" }, { "$ref": "#/components/schemas/listen_error_message" } ], "discriminator": { "propertyName": "object", "mapping": { "transcript_item": "#/components/schemas/listen_transcript_item", "audio_chunk_ack": "#/components/schemas/listen_audio_chunk_ack", "error_message": "#/components/schemas/listen_error_message" } } }, "listen_transcript_item": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transcript_item" ] }, "id": { "$ref": "#/components/schemas/uuid", "description": "ID of the object you're receiving. It will be re-used as you receive more refined versions of this object, until you get the final version (the one for which `is_final` is `true`)." }, "text": { "type": "string", "description": "The transcribed text.", "example": "Also, I’m allergic to peanuts." }, "speaker": { "$ref": "#/components/schemas/legacy_speaker", "description": "Who said the text in this transcript item. If no diarization, then this is simply inferred from the speakerType of the audio stream from which this sentence got transcribed." }, "start_offset_ms": { "type": "integer", "description": "The initial point of the audio segment that this transcript entry represents, measured in milliseconds from the start of the audio stream.", "example": 65100 }, "end_offset_ms": { "type": "integer", "description": "The concluding point of the audio segment that this transcript entry represents, measured in milliseconds from the start of the audio stream.\n\nIn other words: this basically equals `start_time_ms` plus the duration of the audio segment that this transcript entry represents (regardless of how it was chunked).", "example": 69300 }, "is_final": { "type": "boolean", "description": "Indicates if this is the final version of the transcript item." } }, "required": [ "object", "id", "text", "speaker", "start_offset_ms", "end_offset_ms", "is_final" ] }, "listen_audio_chunk_ack": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "audio_chunk_ack" ] }, "stream_id": { "type": "string", "description": "ID of the stream to which the ack-ed chunk belongs." }, "ack_id": { "type": "integer", "description": "The sequential id of the audio chunk up to which this acknowledgment applies." } }, "example": { "object": "audio_chunk_ack", "stream_id": "patient_stream", "ack_id": 42 }, "required": [ "object", "ack_id", "stream_id" ] }, "listen_error_message": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "error_message" ] }, "message": { "type": "string", "description": "The error message." } }, "required": [ "object", "message" ], "example": { "object": "error_message", "message": "Unable to parse JSON at path $.language" } }, "smart_dictate_config": { "type": "object", "description": "First message to configure dictation (audio format, locale, etc).\nUnlike older WebSocket APIs, the Dictation API now consistently requires sequence ids in incoming audio chunks and always emits audio chunk acknowledgment frames.\n \nRead more in [Make transcription and dictation resilient to network interruptions](/guides/best-practices/transcription-network-resilience).", "properties": { "type": { "type": "string", "enum": [ "CONFIG" ] }, "encoding": { "$ref": "#/components/schemas/audio_encoding" }, "sample_rate": { "type": "integer", "description": "Sample rate of submitted streaming audio, in hertz.", "minimum": 8000, "maximum": 192000, "example": 16000 }, "dictation_locale": { "$ref": "#/components/schemas/dictate_locale", "description": "Language spoken in the audio." }, "punctuation_mode": { "$ref": "#/components/schemas/punctuation_mode" }, "text_field_context": { "$ref": "#/components/schemas/smart_dictate_config_text_field_context" } }, "required": [ "type", "encoding", "sample_rate", "dictation_locale", "punctuation_mode" ] }, "smart_dictate_audio_chunk": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK" ] }, "payload": { "type": "string", "description": "Raw audio chunk in base64 string.", "example": "ZXhhbXBsZQ==" }, "seq_id": { "type": "integer", "description": "A unique identifier for this audio chunk, expected to be sequential (n+1) from one audio chunk to the next.\nFirst value can start at any arbitrary value.\nRead more in [Make transcription and dictation resilient to network interruptions](/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "payload", "seq_id" ] }, "smart_dictate_end": { "$ref": "#/components/schemas/dictate_end" }, "smart_dictate_output": { "oneOf": [ { "$ref": "#/components/schemas/smart_dictate_dictated_text" }, { "$ref": "#/components/schemas/smart_dictate_audio_chunk_ack" }, { "$ref": "#/components/schemas/ws_error_message" } ], "discriminator": { "propertyName": "type", "mapping": { "DICTATED_TEXT": "#/components/schemas/smart_dictate_dictated_text", "AUDIO_CHUNK_ACK": "#/components/schemas/smart_dictate_audio_chunk_ack", "ERROR_MESSAGE": "#/components/schemas/ws_error_message" } } }, "smart_dictate_audio_chunk_ack": { "type": "object", "description": "Acknowledgement of audio receipt by the server up to the audio chunk with the sequential id `ack_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/guides/best-practices/transcription-network-resilience).", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK_ACK" ] }, "ack_id": { "type": "integer", "description": "The sequential id of the audio chunk up to which this acknowledgment applies." } }, "example": { "type": "AUDIO_CHUNK_ACK", "ack_id": 42 }, "required": [ "type", "ack_id" ] }, "smart_dictate_dictated_text": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DICTATED_TEXT" ] }, "text": { "type": "string", "description": "The dictated text.", "example": "Patient showed " } }, "required": [ "type", "text" ] }, "dictate_config": { "type": "object", "description": "First message to configure dictation (audio format, locale, etc).", "properties": { "type": { "type": "string", "enum": [ "CONFIG" ] }, "encoding": { "$ref": "#/components/schemas/audio_encoding" }, "sample_rate": { "type": "integer", "description": "Sample rate of submitted streaming audio, in hertz.", "minimum": 8000, "maximum": 192000, "example": 16000 }, "speech_locale": { "$ref": "#/components/schemas/speech_locale", "description": "Language spoken in the audio." }, "dictate_punctuation": { "type": "boolean", "description": "When enabled, the speaker dictating would explicitly dictate the punctuation.\nFor instance, when the dictating provider says:\n\n_The patient inquired **quotation mark** is this an allergy **question mark** **close quotation mark** displaying significant distress_.\n\nthe transcription would output:\n\n`The patient inquired \"is this an allergy?\" displaying significant distress.`." }, "enable_audio_chunk_ack": { "type": "boolean", "default": false, "description": "If enabled, audio chunks should contain a `seq_id`, and the server will periodically send acknowledgements up to the specified `seq_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "encoding", "sample_rate", "speech_locale", "dictate_punctuation" ] }, "dictate_audio_chunk": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK" ] }, "payload": { "type": "string", "description": "Raw audio chunk in base64 string.", "example": "ZXhhbXBsZQ==" }, "seq_id": { "type": "integer", "description": "A unique identifier for this audio chunk within its stream, expected to be sequential (n+1) from one audio chunk to the next.\nFirst value (i.e. for the first audio chunk of a stream) can start at any arbitrary value.\nThis field is required if you enabled the audio chunk acknowledgement protocol in the configuration.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "payload" ] }, "dictate_end": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "END" ] } }, "required": [ "type" ], "example": { "type": "END" } }, "dictate_output": { "oneOf": [ { "$ref": "#/components/schemas/dictate_dictation_item" }, { "$ref": "#/components/schemas/dictate_audio_chunk_ack" }, { "$ref": "#/components/schemas/dictate_error_message" } ], "discriminator": { "propertyName": "type", "mapping": { "DICTATION_ITEM": "#/components/schemas/dictate_dictation_item", "AUDIO_CHUNK_ACK": "#/components/schemas/dictate_audio_chunk_ack", "ERROR_MESSAGE": "#/components/schemas/dictate_error_message" } } }, "dictate_audio_chunk_ack": { "type": "object", "description": "Acknowledgement of audio receipt by the server up to the audio chunk with the sequential id `ack_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience).", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK_ACK" ] }, "ack_id": { "type": "integer", "description": "The sequential id of the audio chunk up to which this acknowledgment applies." } }, "example": { "type": "AUDIO_CHUNK_ACK", "ack_id": 42 }, "required": [ "type", "ack_id" ] }, "dictate_dictation_item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DICTATION_ITEM" ] }, "id": { "$ref": "#/components/schemas/uuid", "description": "ID of the dictation_item you're receiving. It will be re-used as you receive more refined versions of this item, until you get the final version (the one for which `is_final` is `true`)." }, "text": { "type": "string", "description": "The transcribed text.", "example": "Patient showed signs of rapid improvement." }, "start_offset_ms": { "type": "integer", "description": "The initial point of the audio segment that this dictation entry represents, measured in milliseconds from the start of the audio stream.", "example": 65100 }, "end_offset_ms": { "type": "integer", "description": "The concluding point of the audio segment that this dictation entry represents, measured in milliseconds from the start of the audio stream.\n\nIn other words: this basically equals `start_time_ms` plus the duration of the audio segment that this dictation entry represents (regardless of how it was chunked).", "example": 69300 }, "is_final": { "type": "boolean", "description": "Indicates if this is the final version of the dictation item." } }, "required": [ "type", "id", "text", "start_offset_ms", "end_offset_ms", "is_final" ] }, "dictate_error_message": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ERROR_MESSAGE" ] }, "message": { "type": "string", "description": "A human-readable explanation of the error, often including contextual details to help understand what went wrong." }, "code": { "type": "integer", "description": "A numeric identifier for the error. This may either be a standard HTTP status code (e.g. 400, 401) or a more specific application-level code (typically >1000). Some errors —like an audio buffer overflow due to client misuse— have dedicated codes, while others —like malformed JSON— use broader and generic codes.\n\n**Tip**: You should use this field as the primary reference for implementing error handling logic." }, "name": { "type": "string", "description": "An internal enum-style name associated with the error code. While it may help with debugging, it’s mainly for reference—always rely on the numeric code for programmatic handling." }, "trace_id": { "type": "string", "description": "A unique identifier for the failed API request. This is especially useful when reaching out to Nabla support, as it allows us to trace the exact request in our systems." } }, "required": [ "type", "message", "code", "name" ], "example": [ { "type": "ERROR_MESSAGE", "message": "Unable to parse JSON at path $.speech_locales", "code": 400, "name": "BAD_REQUEST", "trace_id": "projects/xxxxx/traces/abcd123456789xyz" }, { "type": "ERROR_MESSAGE", "message": "Received a huge amount of audio in a very short window time.", "code": 83016, "name": "AUDIO_CHUNKS_BUFFER_OVERFLOW", "trace_id": "projects/xxxxx/traces/abcd123456789xyz" } ] }, "legacy_dictate_config": { "type": "object", "description": "First message to configure dictation (audio format, locale, etc).", "properties": { "type": { "type": "string", "enum": [ "dictate_config" ] }, "encoding": { "$ref": "#/components/schemas/old_audio_encoding" }, "sample_rate": { "type": "integer", "description": "Sample rate of submitted streaming audio, in hertz.", "example": 16000 }, "locale": { "$ref": "#/components/schemas/legacy_speech_locale", "description": "Language spoken in the audio." }, "dictate_punctuation": { "type": "boolean", "description": "When enabled, the speaker dictating would explicitly dictate the punctuation.\nFor instance, when the dictating provider says:\n\n_The patient inquired **quotation mark** is this an allergy **question mark** **close quotation mark** displaying significant distress_.\n\nthe transcription would output:\n\n`The patient inquired \"is this an allergy?\" displaying significant distress.`." }, "enable_audio_chunk_ack": { "type": "boolean", "default": false, "description": "If enabled, audio chunks should contain a `seq_id`, and the server will periodically send acknowledgements up to the specified `seq_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "encoding", "sample_rate", "locale", "dictate_punctuation" ] }, "legacy_dictate_audio_chunk": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "audio_chunk" ] }, "payload": { "type": "string", "description": "Raw audio chunk in base64 string.", "example": "ZXhhbXBsZQ==" }, "seq_id": { "type": "integer", "description": "A unique identifier for this audio chunk within its stream, expected to be sequential (n+1) from one audio chunk to the next.\nFirst value (i.e. for the first audio chunk of a stream) can start at any arbitrary value.\nThis field is required if you enabled the audio chunk acknowledgement protocol in the configuration.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience)." } }, "required": [ "type", "payload" ] }, "legacy_dictate_end": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "type" ], "example": { "type": "end" } }, "legacy_dictate_output": { "oneOf": [ { "$ref": "#/components/schemas/legacy_dictate_dictation_item" }, { "$ref": "#/components/schemas/legacy_dictate_audio_chunk_ack" }, { "$ref": "#/components/schemas/legacy_dictate_error_message" } ], "discriminator": { "propertyName": "type", "mapping": { "dictation_item": "#/components/schemas/legacy_dictate_dictation_item", "audio_chunk_ack": "#/components/schemas/legacy_dictate_audio_chunk_ack", "error_message": "#/components/schemas/legacy_dictate_error_message" } } }, "legacy_dictate_audio_chunk_ack": { "type": "object", "description": "Acknowledgement of audio receipt by the server up to the audio chunk with the sequential id `ack_id`.\n\nRead more in [Make transcription and dictation resilient to network interruptions](/next/guides/best-practices/transcription-network-resilience).", "properties": { "type": { "type": "string", "enum": [ "AUDIO_CHUNK_ACK" ] }, "ack_id": { "type": "integer", "description": "The sequential id of the audio chunk up to which this acknowledgment applies." } }, "example": { "type": "audio_chunk_ack", "ack_id": 42 }, "required": [ "type", "ack_id" ] }, "legacy_dictate_dictation_item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dictation_item" ] }, "id": { "$ref": "#/components/schemas/uuid", "description": "ID of the dictation_item you're receiving. It will be re-used as you receive more refined versions of this item, until you get the final version (the one for which `is_final` is `true`)." }, "text": { "type": "string", "description": "The transcribed text.", "example": "Patient showed signs of rapid improvement." }, "start_offset_ms": { "type": "integer", "description": "The initial point of the audio segment that this dictation entry represents, measured in milliseconds from the start of the audio stream.", "example": 65100 }, "end_offset_ms": { "type": "integer", "description": "The concluding point of the audio segment that this dictation entry represents, measured in milliseconds from the start of the audio stream.\n\nIn other words: this basically equals `start_time_ms` plus the duration of the audio segment that this dictation entry represents (regardless of how it was chunked).", "example": 69300 }, "is_final": { "type": "boolean", "description": "Indicates if this is the final version of the dictation item." } }, "required": [ "type", "id", "text", "start_offset_ms", "end_offset_ms", "is_final" ] }, "legacy_dictate_error_message": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "error_message" ] }, "message": { "type": "string", "description": "The error message." } }, "required": [ "type", "message" ], "example": { "type": "error_message", "message": "Unable to parse JSON at path $.language" } }, "api_webhook_event": { "$ref": "#/components/schemas/webhook_event" }, "generate_note_async.succeeded": { "$ref": "#/components/schemas/generate_note_async_succeeded" }, "generate_note_async.failed": { "$ref": "#/components/schemas/generate_note_async_failed" }, "transcribe_async.succeeded": { "$ref": "#/components/schemas/transcribe_async_succeeded" }, "transcribe_async.failed": { "$ref": "#/components/schemas/transcribe_async_failed" }, "dictate_async.succeeded": { "$ref": "#/components/schemas/dictate_async_succeeded" }, "dictate_async.failed": { "$ref": "#/components/schemas/dictate_async_failed" }, "jwt_token": { "type": "string", "description": "An authentication token using the JWT serialization format. JWT tokens contain varying data (depending on their intended use) and use a signature to guarantee their authenticity.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwic3ViIjoiMTIzNDU2Nzg5MCIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMn0.v5qdy8w9Ygs5fdic9a1LuX76PUdx3omYd5GlDTAF3Ug" }, "speech_locale": { "type": "string", "enum": [ "ENGLISH_US", "ENGLISH_UK", "SPANISH_ES", "SPANISH_MX", "FRENCH_FR", "ARABIC_EG", "ARABIC_LB", "ARABIC_MA", "ARABIC_SA", "ARMENIAN_AM", "BENGALI_IN", "CANTONESE_CN", "CROATIAN_HR", "FILIPINO_PH", "GERMAN_DE", "GREEK_GR", "GUJARATI_IN", "HEBREW_IL", "HINDI_IN", "ITALIAN_IT", "JAPANESE_JP", "KHMER_KH", "KOREAN_KR", "MANDARIN_CN", "PERSIAN_IR", "POLISH_PL", "PORTUGUESE_PT", "PUNJABI_IN", "RUSSIAN_RU", "SERBIAN_RS", "TAMIL_IN", "TELUGU_IN", "THAI_TH", "URDU_IN", "VIETNAMESE_VN" ], "example": "ENGLISH_US" }, "speech_locale_array": { "type": "array", "items": { "$ref": "#/components/schemas/speech_locale" }, "minItems": 1, "maxItems": 2, "uniqueItems": true }, "transcribe_request": { "type": "object", "description": "The object containing all the information needed along with the audio file to transcribe.", "properties": { "speech_locales": { "$ref": "#/components/schemas/speech_locale_array", "description": "An array of up to two locales for transcription. The speech-to-text engine automatically detects the spoken locale from this list." }, "split_by_sentence": { "type": "boolean", "default": false, "description": "Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio." } }, "required": [ "speech_locales" ] }, "speaker": { "type": "string", "enum": [ "DOCTOR", "PATIENT", "UNSPECIFIED" ], "description": "Who said the text in this transcript item.", "example": "DOCTOR" }, "transcript_item": { "type": "object", "description": "A portion of the transcribed consultation.", "properties": { "text": { "type": "string", "description": "The transcribed text.", "example": "Also, I’m allergic to peanuts." }, "speaker_type": { "$ref": "#/components/schemas/speaker" }, "locale": { "$ref": "#/components/schemas/speech_locale", "description": "Locale for this transcript item, detected by the speech-to-text engine from the list of locales in the input." }, "start_offset_ms": { "type": "integer", "description": "Start time of this transcription item as the offset, in milliseconds, from the start of the audio file.", "example": 65100 }, "end_offset_ms": { "type": "integer", "description": "End time of this transcription item as the offset, in milliseconds, from the start of the audio file. Equals the `start_time_ms` plus the duration of the related transcribed audio portion.", "example": 69300 } }, "required": [ "text", "locale", "start_offset_ms", "end_offset_ms" ] }, "transcript": { "type": "array", "description": "Transcript items from the audio file.", "items": { "$ref": "#/components/schemas/transcript_item" } }, "transcribe_response": { "type": "object", "properties": { "transcript": { "$ref": "#/components/schemas/transcript" } }, "required": [ "transcript" ] }, "client_request_id": { "type": "string", "maxLength": 128, "description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID." }, "transcribe_async_request": { "type": "object", "description": "The object containing all the information needed along with the audio file to transcribe.", "properties": { "speech_locales": { "$ref": "#/components/schemas/speech_locale_array", "description": "An array of up to two locales for transcription. The speech-to-text engine automatically detects the spoken locale from this list." }, "file_url": { "type": "string", "description": "The URL of the audio file to download & transcribe." }, "split_by_sentence": { "type": "boolean", "default": false, "description": "Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" } }, "required": [ "speech_locales", "file_url" ] }, "uuid": { "type": "string", "format": "uuid", "description": "A unique identifier.", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6" }, "async_request_status": { "type": "string", "enum": [ "ONGOING", "FAILED", "SUCCEEDED" ] }, "async_request_ongoing": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The id of the asynchronous request." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" }, "status": { "$ref": "#/components/schemas/async_request_status" } }, "required": [ "id", "status" ] }, "async_request_failed_payload": { "type": "object", "properties": { "error_code": { "type": "integer", "example": 422 }, "error_message": { "type": "string", "example": "We can't generate the note when the transcript is too short." } }, "required": [ "error_code" ] }, "async_request_failed": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The id of the asynchronous request." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" }, "status": { "$ref": "#/components/schemas/async_request_status" }, "payload": { "$ref": "#/components/schemas/async_request_failed_payload" } }, "required": [ "id", "status", "payload" ] }, "async_transcription_succeeded_payload": { "type": "object", "description": "The generated transcript.", "properties": { "transcript": { "$ref": "#/components/schemas/transcript" } }, "required": [ "transcript" ] }, "async_transcription_succeeded": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The id of the asynchronous request." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" }, "status": { "$ref": "#/components/schemas/async_request_status" }, "payload": { "$ref": "#/components/schemas/async_transcription_succeeded_payload" } }, "required": [ "id", "status" ] }, "async_transcription": { "oneOf": [ { "$ref": "#/components/schemas/async_request_ongoing", "title": "ONGOING" }, { "$ref": "#/components/schemas/async_request_failed", "title": "FAILED" }, { "$ref": "#/components/schemas/async_transcription_succeeded", "title": "SUCCEEDED" } ], "discriminator": { "propertyName": "status", "mapping": { "ONGOING": "#/components/schemas/async_request_ongoing", "FAILED": "#/components/schemas/async_request_failed", "SUCCEEDED": "#/components/schemas/async_transcription_succeeded" } } }, "dictate_locale": { "type": "string", "enum": [ "ENGLISH_US", "ENGLISH_UK", "SPANISH_ES", "SPANISH_MX", "FRENCH_FR" ], "example": "ENGLISH_US" }, "punctuation_mode": { "type": "string", "enum": [ "EXPLICIT" ], "description": "Specifies how punctuation is handled. Possible values are:
• `EXPLICIT`: speaker must explicitly dictate punctuation (e.g. \"comma\" or \"quotation mark\")." }, "dictate_request": { "type": "object", "description": "The object containing all the information needed along with the audio file for which you want dictation.", "properties": { "dictation_locale": { "$ref": "#/components/schemas/dictate_locale" }, "punctuation_mode": { "$ref": "#/components/schemas/punctuation_mode" } }, "required": [ "dictation_locale", "punctuation_mode" ] }, "dictate_response": { "type": "object", "properties": { "dictation": { "type": "string" } }, "required": [ "dictation" ] }, "dictate_async_request": { "type": "object", "description": "The object containing all the information needed along with the audio file for which you want dictation.", "properties": { "dictation_locale": { "$ref": "#/components/schemas/dictate_locale" }, "file_url": { "type": "string", "description": "The URL of the audio file to download & generate dictation." }, "punctuation_mode": { "$ref": "#/components/schemas/punctuation_mode" }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" } }, "required": [ "dictation_locale", "file_url", "punctuation_mode" ] }, "async_dictation_succeeded_payload": { "type": "object", "description": "The generated dictation.", "properties": { "dictation": { "type": "string", "description": "The generated dictation string." } }, "required": [ "dictation" ] }, "async_dictation_succeeded": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The id of the asynchronous request." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" }, "status": { "$ref": "#/components/schemas/async_request_status" }, "payload": { "$ref": "#/components/schemas/async_dictation_succeeded_payload" } }, "required": [ "id", "status" ] }, "async_dictation": { "oneOf": [ { "$ref": "#/components/schemas/async_request_ongoing", "title": "ONGOING" }, { "$ref": "#/components/schemas/async_request_failed", "title": "FAILED" }, { "$ref": "#/components/schemas/async_dictation_succeeded", "title": "SUCCEEDED" } ], "discriminator": { "propertyName": "status", "mapping": { "ONGOING": "#/components/schemas/async_request_ongoing", "FAILED": "#/components/schemas/async_request_failed", "SUCCEEDED": "#/components/schemas/async_dictation_succeeded" } } }, "note_locale": { "type": "string", "description": "Locale of the note.", "enum": [ "ENGLISH_US", "ENGLISH_UK", "FRENCH_FR" ], "example": "ENGLISH_US" }, "transcript_item_request": { "type": "object", "description": "A portion of the transcribed consultation.", "properties": { "text": { "type": "string", "description": "The transcribed text.", "example": "Also, I’m allergic to peanuts." }, "speaker_type": { "$ref": "#/components/schemas/speaker" } }, "required": [ "text", "speaker_type" ] }, "note_template": { "type": "string", "enum": [ "GENERIC_MULTIPLE_SECTIONS", "GENERIC_MULTIPLE_SECTIONS_AP_MERGED", "GENERIC_SOAP", "GENERIC_SOAP_AP_MERGED", "GENERIC_SOAP_PLUS_EXAM_TESTS_AP_MERGED", "GENERIC_APSO_AP_MERGED", "EMERGENCY_MULTIPLE_SECTIONS", "EMERGENCY_SOAP", "WCC_MULTIPLE_SECTIONS", "WCC_SOAP", "PSYCHIATRY_MULTIPLE_SECTIONS", "PSYCHIATRY_SOAP", "PSYCHOLOGY_MULTIPLE_SECTIONS", "CARDIOLOGY_MULTIPLE_SECTIONS", "DIET_MULTIPLE_SECTIONS" ], "description": "The template of the note.\n\nSome templates are **only available in specific languages**. Check [Note template](/next/guides/note-templates/note-templates-sections) for details.", "example": "GENERIC_MULTIPLE_SECTIONS" }, "note_section_key": { "type": "string", "description": "A key identifying a section of a note.\nThe set of possible keys depend on the template that is used. Check [Note template](/next/guides/note-templates/note-templates-sections) for possible values.", "example": "CHIEF_COMPLAINT", "enum": [ "ALLERGIES", "APPOINTMENTS", "ASSESSMENT", "ASSESSMENT_AND_PLAN", "CARDIOVASCULAR_RISK_FACTORS", "CHIEF_COMPLAINT", "CURRENT_MEDICATIONS", "DIAGNOSTIC_TESTS_ORDERED", "FOOD_HABITS", "LIFESTYLE", "PAST_MEDICAL_HISTORY", "OBJECTIVES_AND_ADVICE", "FAMILY_HISTORY", "HISTORY_OF_PRESENT_ILLNESS", "IMAGING_RESULTS", "IMMUNIZATIONS", "LAB_RESULTS", "MENTAL_HEALTH_EXAM", "MENTAL_HEALTH_HISTORY", "PAST_OBSTETRIC_HISTORY", "PAST_SURGICAL_HISTORY", "PHYSICAL_EXAM", "PLAN", "PRESCRIPTION", "HISTORY_OF_PRESENT_COMPLAINT", "OBJECTIVE", "SUBJECTIVE", "SOCIAL_HISTORY", "VITALS", "WELL_CHILD_CARE" ] }, "note_section_customization_custom_instruction": { "type": "string", "maxLength": 700, "example": "Include discussion about first symptoms", "description": "Allow to customize a note section by providing specific guidelines. These guidelines must be as clear and concise as possible for best results." }, "note_section_customization_section_style": { "type": "string", "enum": [ "AUTO", "PARAGRAPH", "BULLET_POINTS" ], "example": "PARAGRAPH", "description": "Specifies the desired style for the note section:\n\n • `PARAGRAPH`: Prioritizes generating paragraphs;\n\n • `BULLET_POINTS`: Prioritizes structuring content using bullet points.\n\n • `AUTO`: Automatically picks the most natural formatting option.\n\nDefault is `AUTO`." }, "note_section_customization_level_of_detail": { "type": "string", "enum": [ "DEFAULT", "DETAILED" ], "description": "Specifies the desired level of details. Use `detailed` to get more details in the note section." }, "note_section_customization_request": { "type": "object", "properties": { "section_key": { "description": "Key of the note section this customization should apply to.", "$ref": "#/components/schemas/note_section_key" }, "custom_instruction": { "$ref": "#/components/schemas/note_section_customization_custom_instruction" }, "style": { "$ref": "#/components/schemas/note_section_customization_section_style" }, "level_of_detail": { "$ref": "#/components/schemas/note_section_customization_level_of_detail" }, "split_by_problem": { "type": "boolean", "description": "Flag to structure the content of the note sections according to distinct clinical problems or topics addressed during the consultation." } }, "required": [ "section_key" ] }, "note_section_request": { "type": "object", "description": "A note section.", "properties": { "key": { "$ref": "#/components/schemas/note_section_key" }, "title": { "type": "string", "description": "The section title.", "example": "Chief complaint" }, "text": { "type": "string", "description": "Content of the note section.", "example": "Sleep disorder" } }, "required": [ "key", "title", "text" ] }, "note_request": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the note.", "example": "Fever and strong headache" }, "sections": { "type": "array", "description": "Sections of the note.", "items": { "$ref": "#/components/schemas/note_section_request" } }, "locale": { "$ref": "#/components/schemas/note_locale" }, "template": { "$ref": "#/components/schemas/note_template" } }, "required": [ "sections", "locale", "template" ] }, "icd10_entry_request": { "type": "object", "description": "An ICD-10 entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." } }, "required": [ "code", "display", "system" ] }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "OTHER" ], "description": "The patient's gender." }, "pronouns": { "type": "string", "enum": [ "HE_HIM", "SHE_HER", "THEY_THEM" ], "description": "The patient's pronouns." }, "patient_demographics": { "type": "object", "description": "Demographic details about the patient.", "properties": { "name": { "type": "string", "description": "The patient's name." }, "birth_date": { "type": "string", "format": "date", "description": "The patient's birthdate (YYYY-MM-DD format).", "example": "1996-03-21" }, "gender": { "$ref": "#/components/schemas/gender" }, "pronouns": { "$ref": "#/components/schemas/pronouns" } }, "required": [ "name" ] }, "structured_context_request": { "type": "object", "description": "Structured context about the patient and the encounter, which will be taken into account when generating the note.", "properties": { "encounter_diagnoses_coding": { "type": "array", "description": "The ICD-10 coding for the patient's active encounter diagnoses. If the template used for the note generation contains an `ASSESSMENT_AND_PLAN` section, these diagnoses will be used for the \"by problem\" structuration of this section if they are discussed during the encounter.", "items": { "$ref": "#/components/schemas/icd10_entry_request" } }, "patient_demographics": { "$ref": "#/components/schemas/patient_demographics" }, "draft_assessment_and_plan": { "type": "string", "description": "The text that should be used as a starting point for the generation of the \"Assessment & Plan\" section of the note. It could be text written by the user right before the beginning of the encounter, or the A&P of the previous note in the case when the user is doing a follow-up encounter. If the template used for the note generation contains an `ASSESSMENT_AND_PLAN` section, the provided text will be used for this section and augmented based on the transcript." } } }, "generate_note_request": { "type": "object", "description": "Input for note generation.", "properties": { "note_locale": { "$ref": "#/components/schemas/note_locale" }, "transcript_items": { "type": "array", "description": "The transcript from which to generate the note.\n\nYou don't need to specify each item's start or end time, but make sure they are sorted. In fact, due to its asynchronous nature, our [real-time transcription API](/next/server/transcribe-ws) does not guarantee its results order. Thus, before calling this note-generation API please **filter-out non-final items and sort them by `start_offset_ms`**.", "items": { "$ref": "#/components/schemas/transcript_item_request" } }, "note_template": { "$ref": "#/components/schemas/note_template" }, "note_sections_customization": { "type": "array", "items": { "$ref": "#/components/schemas/note_section_customization_request" }, "description": "Advanced per-section customization options for the chosen template.\n\nYou should **only specify sections that belong to the given template**, and **only specify customization options that are supported for the given section**. Also, only specify sections you want to customize, no need to be exhaustive.\n\n\nCheck [Note templates sections](/next/guides/note-templates/note-customization) for compatibility matrix." }, "current_note": { "$ref": "#/components/schemas/note_request", "description": "Optional note from a previous transcription session, to be updated using the new `transcript_items`.\nThis is useful if you generate notes gradually to avoid accumulating a very long transcript items list.\n\nThe `template` and `locale` fields describe the note being passed in and do not control the output." }, "unstructured_context": { "type": "string", "description": "Some unstructured contextual information that will be used to generate the note (for example name, gender, age, pronouns, medical history). For better information processing, please prioritize passing information in a structured manner via the `structured_context` field.", "maxLength": 700 }, "structured_context": { "$ref": "#/components/schemas/structured_context_request" } }, "required": [ "transcript_items", "note_locale" ] }, "note_section": { "type": "object", "description": "A note section.", "properties": { "key": { "$ref": "#/components/schemas/note_section_key" }, "title": { "type": "string", "description": "The section title.", "example": "Chief complaint" }, "text": { "type": "string", "description": "Content of the note section.", "example": "Sleep disorder" } }, "required": [ "key", "title", "text" ], "example": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "Fatigue and headaches" }, { "key": "SYMPTOMS", "title": "Symptoms", "text": "- Tiredness all day long\n- Mild headaches on the right side" } ] }, "note": { "type": "object", "description": "The generated note.", "properties": { "title": { "type": "string", "description": "Title of the note.", "example": "Fever and strong headache" }, "sections": { "type": "array", "description": "Content of the note structured in multiple sections.", "items": { "$ref": "#/components/schemas/note_section" } }, "locale": { "$ref": "#/components/schemas/note_locale" }, "template": { "$ref": "#/components/schemas/note_template" } }, "required": [ "sections", "locale", "template" ] }, "generate_note_response": { "type": "object", "description": "The generated note.", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/note" } } }, "generate_note_async_request": { "allOf": [ { "$ref": "#/components/schemas/generate_note_request" }, { "type": "object", "properties": { "client_request_id": { "$ref": "#/components/schemas/client_request_id" } } } ] }, "async_note_generation_succeeded_payload": { "type": "object", "description": "The generated note.", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/note" } } }, "async_note_generation_succeeded": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The id of the asynchronous request." }, "client_request_id": { "$ref": "#/components/schemas/client_request_id" }, "status": { "$ref": "#/components/schemas/async_request_status" }, "payload": { "$ref": "#/components/schemas/async_note_generation_succeeded_payload" } }, "required": [ "id", "status" ] }, "async_note_generation": { "oneOf": [ { "$ref": "#/components/schemas/async_request_ongoing", "title": "ONGOING" }, { "$ref": "#/components/schemas/async_request_failed", "title": "FAILED" }, { "$ref": "#/components/schemas/async_note_generation_succeeded", "title": "SUCCEEDED" } ], "discriminator": { "propertyName": "status", "mapping": { "ONGOING": "#/components/schemas/async_request_ongoing", "FAILED": "#/components/schemas/async_request_failed", "SUCCEEDED": "#/components/schemas/async_note_generation_succeeded" } } }, "generate_normalized_data_request": { "type": "object", "properties": { "note": { "$ref": "#/components/schemas/note_request", "description": "The Nabla-generated clinical note to normalize." }, "include_corresponding_note_problems": { "description": "Indicates whether to include, for each condition, the title of the corresponding problem sub-header in the \"Assessment & Plan\" section of the input note. This field will only be returned when an `ASSESSMENT_AND_PLAN` section has been provided in the input note.", "type": "boolean", "default": false }, "encounter_diagnoses_coding": { "type": "array", "description": "The ICD-10 coding for the patient's active encounter diagnoses. If some of them are found to apply to the current note, they will be prioritized in the normalization process.", "items": { "$ref": "#/components/schemas/icd10_entry_request" } } }, "required": [ "note" ] }, "fhir_condition_clinical_status": { "type": "string", "enum": [ "ACTIVE", "RESOLVED" ], "description": "The [clinical status](https://www.hl7.org/fhir/condition-definitions.html#Condition.clinicalStatus) of the condition. Only `ACTIVE` and `RESOLVED` are supported for now.", "example": "ACTIVE" }, "icd10_entry_with_hcc_mcc": { "type": "object", "description": "An ICD-10 entry including HCC and MCC information.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "is_hcc": { "description": "Indicates if this code maps to a Hierarchical Condition Category (HCC) under the version 28 risk adjustment model.", "type": "boolean" }, "is_mcc": { "description": "Indicates if this code qualifies as a Major Complication or Comorbidity (MCC).", "type": "boolean" } }, "required": [ "code", "display", "system", "is_hcc", "is_mcc" ] }, "fhir_condition_category": { "type": "string", "enum": [ "PROBLEM_LIST_ITEM", "ENCOUNTER_DIAGNOSIS" ], "description": "The category of a [FHIR condition](https://www.hl7.org/fhir/condition.html).", "example": "PROBLEM_LIST_ITEM" }, "fhir_patient_condition": { "type": "object", "description": "Structured [FHIR condition](https://www.hl7.org/fhir/condition.html).", "properties": { "clinical_status": { "$ref": "#/components/schemas/fhir_condition_clinical_status" }, "coding": { "$ref": "#/components/schemas/icd10_entry_with_hcc_mcc", "description": "ICD-10 coding representation of this condition." }, "alternative_coding": { "type": "array", "description": "An array of ICD-10 codes that are closely related to the primary coding and represent plausible alternative coding for the condition.", "items": { "$ref": "#/components/schemas/icd10_entry_with_hcc_mcc" } }, "categories": { "description": "Categories of the condition.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_condition_category" } }, "corresponding_note_problem": { "description": "The title of the problem sub-header corresponding to this condition, in the \"Assessment & Plan\" section of the input note. This field is only filled when `include_corresponding_note_problems` is set to `true` in the request and that an `ASSESSMENT_AND_PLAN` section has been provided in the input note. If the condition was not extracted from the `ASSESSMENT_AND_PLAN` section, this field will be `null`.", "type": "string" } }, "required": [ "coding" ] }, "icd10_entry": { "type": "object", "description": "An ICD-10 entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." } }, "required": [ "code", "display", "system" ] }, "fhir_family_member_condition": { "type": "object", "description": "Structured [FHIR condition](https://www.hl7.org/fhir/condition.html).", "properties": { "clinical_status": { "$ref": "#/components/schemas/fhir_condition_clinical_status" }, "coding": { "$ref": "#/components/schemas/icd10_entry", "description": "ICD-10 coding representation of this condition." }, "categories": { "description": "Categories of the condition.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_condition_category" } } }, "required": [ "coding" ] }, "family_member_conditions_relationship": { "type": "string", "description": "The relation to the patient of the family member the extracted conditions relate to, if applies.", "enum": [ "MOTHER", "FATHER", "BROTHER", "SISTER", "SON", "DAUGHTER", "GRANDMOTHER", "GRANDFATHER", "AUNT", "UNCLE", "OTHER" ] }, "family_member_conditions": { "type": "object", "properties": { "conditions": { "description": "Conditions of the family member of the patient.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_family_member_condition" } }, "relationship": { "$ref": "#/components/schemas/family_member_conditions_relationship" } } }, "loinc_entry": { "type": "object", "description": "A LOINC entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only LOINC is supported for now.", "enum": [ "http://loinc.org" ] }, "code": { "type": "string", "example": "29463-7", "description": "Code of the LOINC entry." }, "display": { "type": "string", "example": "Body weight", "description": "Description of the LOINC entry." } }, "required": [ "code", "display", "system" ] }, "observation_value_unit": { "type": "string", "description": "The unit of the observation quantity.", "enum": [ "METER", "CENTIMETER", "FOOT", "KILOGRAM", "POUND", "MILLIMETERS_OF_MERCURY", "CENTIMETERS_OF_MERCURY", "CELSIUS", "FAHRENHEIT", "BEATS_PER_MINUTE", "BREATHS_PER_MINUTE", "LITER_PER_MINUTE", "MILLIMETER", "PERCENT", "INCH" ] }, "observation_value_quantity": { "type": "object", "description": "Value quantity for an observation.", "properties": { "value": { "type": "number", "description": "The value of the quantity." }, "unit": { "$ref": "#/components/schemas/observation_value_unit" }, "system": { "type": "string", "description": "The used coding system, only UCUM is supported for now.", "enum": [ "https://ucum.org" ] }, "code": { "type": "string", "description": "The [UCUM](https://ucum.org/ucum.html) code of the unit.", "example": "kg" } }, "required": [ "value", "system" ] }, "observation_value_range": { "type": "object", "description": "Value range for an observation.", "properties": { "low": { "$ref": "#/components/schemas/observation_value_quantity", "description": "The lower bound of the range." }, "high": { "$ref": "#/components/schemas/observation_value_quantity", "description": "The higher bound of the range." } }, "required": [ "low", "high" ] }, "observation_entry": { "type": "object", "description": "Structured [FHIR observation](https://www.hl7.org/fhir/observation.html).", "properties": { "coding": { "$ref": "#/components/schemas/loinc_entry", "description": "LOINC coding representation of this observation." }, "value_quantity": { "$ref": "#/components/schemas/observation_value_quantity", "description": "The value quantity for this observation, if not a range." }, "value_range": { "$ref": "#/components/schemas/observation_value_range", "description": "The value range for this observation, if not a quantity." }, "note": { "type": "string", "description": "Additional comment about the observation.", "example": "Measured at rest." } }, "required": [ "coding" ] }, "normalized_data": { "type": "object", "description": "Normalized data extracted from the note.", "properties": { "conditions": { "description": "FHIR conditions (including their ICD-10 code) corresponding to the patient's medical conditions as mentioned in the clinical note.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_patient_condition" } }, "family_history": { "description": "FHIR conditions (including their ICD-10 code) representing family medical history details extracted from the clinical note. Each element includes the relationship to the patient and the list of related conditions.", "type": "array", "items": { "$ref": "#/components/schemas/family_member_conditions" } }, "observations": { "description": "FHIR observations (including their LOINC code) extracted from the clinical note.", "type": "array", "items": { "$ref": "#/components/schemas/observation_entry" } } }, "required": [ "conditions", "family_history", "observations" ] }, "patient_instructions_recipient_type": { "type": "string", "enum": [ "PATIENT", "PARENT" ], "description": "Recipient type of the patient instructions. This is especially useful for pediatric encounters.", "default": "PATIENT", "example": "PATIENT" }, "generate_patient_instructions_request": { "type": "object", "description": "The input to generate the patient instructions.", "properties": { "note": { "$ref": "#/components/schemas/note_request", "description": "The Nabla-generated clinical note of the encounter." }, "instructions_locale": { "$ref": "#/components/schemas/speech_locale", "description": "Locale of the patient instructions." }, "recipient_type": { "$ref": "#/components/schemas/patient_instructions_recipient_type" } }, "required": [ "note", "instructions_locale" ] }, "generate_patient_instructions_response": { "type": "object", "properties": { "instructions": { "type": "string", "description": "List of instructions for the patient.", "example": "- Order a sleep test that you can do at home. This will help us understand more about how you sleep.\n- After you've done the sleep test, we'll talk about the results in our next meeting." } }, "required": [ "instructions" ] }, "edit_note_with_instructions_request": { "type": "object", "description": "The input to edit the note with instructions.", "properties": { "instructions": { "type": "string", "maxLength": 700, "minLength": 1, "description": "Human-readable text instructions for editing the note. Instructions should be short and straightforward, providing clear direction such as \"Include discussion about…\", \"Make note more concise\", or \"Remove parts about…\". The instructions should help refine and adapt the note to the desired format and content without requiring lengthy or complex prompts.", "example": "Add more details in the Plan section." }, "note": { "$ref": "#/components/schemas/note_request", "description": "The Nabla-generated clinical note of the encounter." }, "transcript_items": { "type": "array", "description": "The same transcript that served to generate the note. This transcript provides essential context, especially when instructions involve capturing more details or detailing specific parts of the encounter.", "items": { "$ref": "#/components/schemas/transcript_item_request" } }, "unstructured_context": { "type": "string", "maxLength": 700, "description": "The same unstructured patient context that served to generate the note, if any. For better information processing, please prioritize passing information in a structured manner via the `structured_context` field.", "example": "28 yo woman with diabetes." }, "structured_context": { "$ref": "#/components/schemas/structured_context_request" }, "note_sections_customization": { "type": "array", "items": { "$ref": "#/components/schemas/note_section_customization_request" } } }, "required": [ "transcript_items", "note", "instructions" ] }, "edit_note_with_instructions_response": { "type": "object", "properties": { "note": { "description": "The new edited note.", "$ref": "#/components/schemas/note" } }, "required": [ "note" ] }, "create_report_payload_generate_note_request_output": { "type": "object", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/note_request" } } }, "create_report_payload_generate_note_request": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "enum": [ "GENERATE_NOTE" ], "description": "The report is about a call to the [Generate Note](/next/server/generate-note) endpoint (or its async version)." }, "input": { "$ref": "#/components/schemas/generate_note_request" }, "output": { "$ref": "#/components/schemas/create_report_payload_generate_note_request_output" }, "expected_output": { "$ref": "#/components/schemas/create_report_payload_generate_note_request_output", "description": "The expected version of `output`. This is typically an improved version of the Nabla-generated note after it has been corrected or adjusted by the healthcare provider." } } }, "create_report_payload_generate_patient_instructions_request_output": { "type": "object", "required": [ "instructions" ], "properties": { "instructions": { "type": "string" } } }, "create_report_payload_generate_patient_instructions_request": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "enum": [ "GENERATE_PATIENT_INSTRUCTIONS" ], "description": "The report is about a call to the [Generate Patient Instructions](/next/server/copilot-generate-patient-instructions) endpoint." }, "input": { "$ref": "#/components/schemas/generate_patient_instructions_request" }, "output": { "$ref": "#/components/schemas/create_report_payload_generate_patient_instructions_request_output" }, "expected_output": { "$ref": "#/components/schemas/create_report_payload_generate_patient_instructions_request_output", "description": "The expected version of `output`. This is typically an improved version of the Nabla-generated patient instructions after they have been corrected or adjusted by the healthcare provider." } } }, "create_report_payload_generate_normalized_data_request_output": { "type": "object", "required": [ "conditions", "family_history" ], "properties": { "conditions": { "description": "FHIR conditions (including their ICD-10 code) corresponding to the patient's medical conditions as mentioned in the clinical note.", "type": "array", "items": { "type": "object", "description": "Structured [FHIR condition](https://www.hl7.org/fhir/condition.html).", "properties": { "clinical_status": { "$ref": "#/components/schemas/fhir_condition_clinical_status" }, "coding": { "type": "object", "description": "An ICD-10 entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." } }, "required": [ "code", "display", "system" ] }, "alternative_coding": { "type": "array", "description": "An array of ICD-10 codes that are closely related to the primary coding and represent plausible alternative coding for the condition.", "items": { "type": "object", "description": "An ICD-10 entry including HCC and MCC information.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." } }, "required": [ "code", "display", "system" ] } }, "categories": { "description": "Categories of the condition.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_condition_category" } }, "corresponding_note_problem": { "type": "string", "description": "The title of the problem sub-header corresponding to this condition, in the \"Assessment & Plan\" section of the input note." } }, "required": [ "coding", "alternative_coding" ] } }, "family_history": { "description": "FHIR conditions (including their ICD-10 code) representing family medical history details extracted from the clinical note. Each element includes the relationship to the patient and the list of related conditions.", "type": "array", "items": { "type": "object", "required": [ "conditions" ], "properties": { "relationship": { "$ref": "#/components/schemas/family_member_conditions_relationship" }, "conditions": { "description": "Conditions of the family member of the patient.", "type": "array", "items": { "type": "object", "description": "Structured [FHIR condition](https://www.hl7.org/fhir/condition.html).", "properties": { "clinical_status": { "$ref": "#/components/schemas/fhir_condition_clinical_status" }, "coding": { "type": "object", "description": "An ICD-10 entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes)." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes)." } }, "required": [ "code", "display" ] }, "categories": { "description": "Categories of the condition.", "type": "array", "items": { "$ref": "#/components/schemas/fhir_condition_category" } } }, "required": [ "coding" ] } } } } }, "observations": { "description": "FHIR observations (including their LOINC code) extracted from the clinical note.", "type": "array", "items": { "type": "object", "description": "Structured [FHIR observation](https://www.hl7.org/fhir/observation.html).", "properties": { "coding": { "type": "object", "description": "LOINC coding representation of this observation.", "properties": { "system": { "type": "string", "description": "The used coding system, only LOINC is supported for now.", "enum": [ "http://loinc.org" ] }, "code": { "type": "string", "example": "29463-7", "description": "Code of the LOINC entry." }, "display": { "type": "string", "example": "Body weight", "description": "Description of the LOINC entry." } }, "required": [ "code", "display", "system" ] }, "value_quantity": { "type": "object", "description": "Value quantity for an observation.", "properties": { "value": { "type": "number", "description": "The value of the quantity." }, "unit": { "$ref": "#/components/schemas/observation_value_unit" }, "system": { "type": "string", "description": "The used coding system, only UCUM is supported for now.", "enum": [ "https://ucum.org" ] }, "code": { "type": "string", "description": "The [UCUM](https://ucum.org/ucum.html) code of the unit.", "example": "kg" } }, "required": [ "value", "system" ] }, "value_range": { "type": "object", "description": "Value range for an observation.", "properties": { "low": { "type": "object", "description": "The lower bound of the range.", "properties": { "value": { "type": "number", "description": "The value of the quantity." }, "unit": { "$ref": "#/components/schemas/observation_value_unit" }, "system": { "type": "string", "description": "The used coding system, only UCUM is supported for now.", "enum": [ "https://ucum.org" ] }, "code": { "type": "string", "description": "The [UCUM](https://ucum.org/ucum.html) code of the unit.", "example": "kg" } }, "required": [ "value", "system" ] }, "high": { "type": "object", "description": "The higher bound of the range.", "properties": { "value": { "type": "number", "description": "The value of the quantity." }, "unit": { "$ref": "#/components/schemas/observation_value_unit" }, "system": { "type": "string", "description": "The used coding system, only UCUM is supported for now.", "enum": [ "https://ucum.org" ] }, "code": { "type": "string", "description": "The [UCUM](https://ucum.org/ucum.html) code of the unit.", "example": "kg" } }, "required": [ "value", "system" ] } }, "required": [ "low", "high" ] }, "note": { "type": "string", "description": "Additional comment about the observation.", "example": "Measured at rest." } }, "required": [ "coding" ] } } } }, "create_report_payload_generate_normalized_data_request": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "enum": [ "GENERATE_NORMALIZED_DATA" ], "description": "The report is about a call to the [Generate Normalized Data](/next/server/generate-normalized-data) endpoint." }, "input": { "$ref": "#/components/schemas/generate_normalized_data_request" }, "output": { "$ref": "#/components/schemas/create_report_payload_generate_normalized_data_request_output" }, "expected_output": { "description": "The expected version of `output`. This is typically an improved version of the Nabla-generated normalized data after it has been corrected or adjusted by the healthcare provider.", "$ref": "#/components/schemas/create_report_payload_generate_normalized_data_request_output" } } }, "create_report_payload_request": { "description": "Input and output of the related API call.", "oneOf": [ { "title": "GENERATE_NOTE", "$ref": "#/components/schemas/create_report_payload_generate_note_request" }, { "title": "GENERATE_PATIENT_INSTRUCTIONS", "$ref": "#/components/schemas/create_report_payload_generate_patient_instructions_request" }, { "title": "GENERATE_NORMALIZED_DATA", "$ref": "#/components/schemas/create_report_payload_generate_normalized_data_request" } ], "discriminator": { "propertyName": "endpoint", "mapping": { "GENERATE_NOTE": "#/components/schemas/create_report_payload_generate_note_request", "GENERATE_PATIENT_INSTRUCTIONS": "#/components/schemas/create_report_payload_generate_patient_instructions_request", "GENERATE_NORMALIZED_DATA": "#/components/schemas/create_report_payload_generate_normalized_data_request" } } }, "create_report_request": { "type": "object", "description": "Input of the report.", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Optional rating for the output of the given response: from very bad (1) to perfect (5)." }, "feedback": { "type": "string", "description": "Feedback on the given response. This should typically explain the rating, suggest specific improvements or highlight the good points." }, "reply_to": { "type": "string", "format": "email", "description": "Optional email address for Nabla to contact for additional information or clarification regarding the submitted report feedback." }, "payload": { "$ref": "#/components/schemas/create_report_payload_request" } }, "required": [ "payload" ] }, "metadata": { "type": "object", "description": "You can use this parameter to attach key-value data to the object. You can specify up to 50 keys, with key names up to 40 characters long, all values must be of type string and up to 500 characters long.\n\nYou should **not** use this to store Protected Health Information (PHI) or any patient-related data.", "nullable": true, "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 50 }, "created_at": { "type": "string", "format": "date-time", "description": "The creation date of this object, in ISO 8601 format.", "example": "2022-03-10T19:16:23.456Z" }, "user": { "type": "object", "description": "The user object.", "properties": { "id": { "$ref": "#/components/schemas/uuid" }, "activated": { "type": "boolean", "description": "Always true unless you explicitly [deactivate](/next/server/deactivate-copilot-user) the user." }, "external_id": { "type": "string", "description": "A unique identifier for the user from another system which is given to Nabla.", "nullable": true, "maxLength": 256 }, "metadata": { "$ref": "#/components/schemas/metadata" }, "created_at": { "$ref": "#/components/schemas/created_at" } }, "required": [ "id", "activated", "created_at" ] }, "next_cursor": { "type": "string", "nullable": true, "description": "An opaque cursor to fetch the next page of the collection." }, "session_tokens": { "type": "object", "description": "The tokens for an authenticated session.", "properties": { "access_token": { "$ref": "#/components/schemas/jwt_token", "description": "A (typically) short-lived JWT token used to access authenticated resources, e.g. the Nabla User API." }, "refresh_token": { "$ref": "#/components/schemas/jwt_token", "description": "A (typically) long-lived JWT token allowing you to \"refresh\" your access to resources (i.e. extend your session, returning a fresh access token and a new refresh token with a later expiration)." } }, "required": [ "access_token", "refresh_token" ] }, "transcribe_config_stream": { "type": "object", "properties": { "id": { "type": "string", "description": "Give an identifier to this stream.", "example": "doctor_stream" }, "speaker_type": { "$ref": "#/components/schemas/speaker", "description": "Who is going to speak in this audio stream." } }, "required": [ "id", "speaker_type" ] }, "audio_encoding": { "type": "string", "description": "Encoding of the streamed audio.", "enum": [ "PCM_S16LE" ], "example": "PCM_S16LE" }, "transcribe_transcript_item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TRANSCRIPT_ITEM" ] }, "id": { "$ref": "#/components/schemas/uuid", "description": "ID of the object you're receiving. It will be re-used as you receive more refined versions of this object, until you get the final version (the one for which `is_final` is `true`)." }, "text": { "type": "string", "description": "The transcribed text.", "example": "Also, I’m allergic to peanuts." }, "speaker_type": { "$ref": "#/components/schemas/speaker", "description": "Who said the text in this transcript item. If no diarization, then this is simply inferred from the speaker type of the audio stream from which this sentence got transcribed." }, "locale": { "$ref": "#/components/schemas/speech_locale", "description": "Locale for this transcript item, detected by the speech-to-text engine from the list of locales in the input." }, "start_offset_ms": { "type": "integer", "description": "The initial point of the audio segment that this transcript entry represents, measured in milliseconds from the start of the audio stream.", "example": 65100 }, "end_offset_ms": { "type": "integer", "description": "The concluding point of the audio segment that this transcript entry represents, measured in milliseconds from the start of the audio stream.\n\nIn other words: this basically equals `start_time_ms` plus the duration of the audio segment that this transcript entry represents (regardless of how it was chunked).", "example": 69300 }, "is_final": { "type": "boolean", "description": "Indicates if this is the final version of the transcript item." } }, "required": [ "type", "id", "text", "speaker_type", "locale", "start_offset_ms", "end_offset_ms", "is_final" ] }, "legacy_speaker": { "type": "string", "enum": [ "doctor", "patient", "unspecified" ], "description": "Who said the text in this transcript item.", "example": "doctor" }, "listen_config_stream": { "type": "object", "properties": { "id": { "type": "string", "description": "Give an identifier to this stream.", "example": "doctor_stream" }, "speaker_type": { "$ref": "#/components/schemas/legacy_speaker", "description": "Who is going to speak in this audio stream." } }, "required": [ "id", "speaker_type" ] }, "old_audio_encoding": { "type": "string", "description": "Encoding of the streamed audio.", "enum": [ "pcm_s16le" ], "example": "pcm_s16le" }, "legacy_language": { "type": "string", "description": "Language of the transcript and the note ('fr' and 'en' are deprecated, and correspond to 'fr-FR' and 'en-US' respectively. Generating a note in 'es-ES' and 'es-MX' is not supported and will be soon removed).", "enum": [ "fr", "en", "en-US", "en-GB", "fr-FR", "es-ES", "es-MX" ], "example": "en-US" }, "smart_dictate_config_text_field_context": { "type": "object", "description": "Information about the text field in which the user is currently dictating. Having this information ensures that capitalization of the first word of the dictation is correct. It contains:\n* **`text`** – the full, current content of the text field. \n* **`selection_start`** / **`selection_length`** – either \n * the caret position where the dictation result will be **inserted** when nothing is selected (in that case `selection_start` is the cursor index and `selection_length = 0`).\n * the range of text currently selected and expected to be **replaced** by the dictation WebSocket output.\n\nValidation rules (violations will close the WebSocket with code 1002 Protocol Error):\n1. `0 ≤ selection_start ≤ text.length` \n2. Let `selection_end = selection_start + selection_length`. It must satisfy `selection_end ≤ text.length`.", "properties": { "text": { "type": "string", "description": "Text content of the text field.", "maxLength": 50000 }, "selection_start": { "type": "integer", "description": "Selection start of the cursor in the text field.", "minimum": 0 }, "selection_length": { "type": "integer", "description": "Selection length of the cursor in the text field.", "minimum": 0 } }, "required": [ "text", "selection_start", "selection_length" ] }, "legacy_speech_locale": { "type": "string", "description": "Language of the transcript.", "enum": [ "en-US", "en-GB", "fr-FR", "es-ES", "es-MX" ], "example": "en-US" }, "base_webhook_event": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/uuid", "description": "The unique identifier of this webhook event." }, "created_at": { "$ref": "#/components/schemas/created_at", "description": "Creation date of this webhook event." }, "type": { "type": "string", "description": "Type of this event, serves as a discriminator between the different possible webhook types." } }, "required": [ "id", "created_at", "type" ] }, "generate_note_async_succeeded": { "x-sensitive-medical-data": true, "x-webhook-type": "CORE_API_GENERATE_NOTE_ASYNC_SUCCEEDED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** note generation succeeds.", "properties": { "data": { "$ref": "#/components/schemas/async_note_generation_succeeded" } }, "required": [ "data" ] } ] }, "generate_note_async_failed": { "x-sensitive-medical-data": false, "x-webhook-type": "CORE_API_GENERATE_NOTE_ASYNC_FAILED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** note generation fails.", "properties": { "data": { "$ref": "#/components/schemas/async_request_failed" } }, "required": [ "data" ] } ] }, "transcribe_async_succeeded": { "x-sensitive-medical-data": true, "x-webhook-type": "CORE_API_TRANSCRIBE_ASYNC_SUCCEEDED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** transcription succeeds.", "properties": { "data": { "$ref": "#/components/schemas/async_transcription_succeeded" } }, "required": [ "data" ] } ] }, "transcribe_async_failed": { "x-sensitive-medical-data": false, "x-webhook-type": "CORE_API_TRANSCRIBE_ASYNC_FAILED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** transcription fails.", "properties": { "data": { "$ref": "#/components/schemas/async_request_failed" } }, "required": [ "data" ] } ] }, "dictate_async_succeeded": { "x-sensitive-medical-data": true, "x-webhook-type": "CORE_API_DICTATE_ASYNC_SUCCEEDED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** dictation succeeds.", "properties": { "data": { "$ref": "#/components/schemas/async_dictation_succeeded" } }, "required": [ "data" ] } ] }, "dictate_async_failed": { "x-sensitive-medical-data": false, "x-webhook-type": "CORE_API_DICTATE_ASYNC_FAILED", "allOf": [ { "$ref": "#/components/schemas/base_webhook_event" }, { "type": "object", "description": "Event sent when an **asynchronous** dictation fails.", "properties": { "data": { "$ref": "#/components/schemas/async_request_failed" } }, "required": [ "data" ] } ] }, "webhook_event": { "oneOf": [ { "$ref": "#/components/schemas/generate_note_async_succeeded", "title": "generate_note_async.succeeded" }, { "$ref": "#/components/schemas/generate_note_async_failed", "title": "generate_note_async.failed" }, { "$ref": "#/components/schemas/transcribe_async_succeeded", "title": "transcribe_async.succeeded" }, { "$ref": "#/components/schemas/transcribe_async_failed", "title": "transcribe_async.failed" }, { "$ref": "#/components/schemas/dictate_async_succeeded", "title": "dictate_async.succeeded" }, { "$ref": "#/components/schemas/dictate_async_failed", "title": "dictate_async.failed" } ], "discriminator": { "propertyName": "type", "mapping": { "generate_note_async.succeeded": "#/components/schemas/generate_note_async_succeeded", "generate_note_async.failed": "#/components/schemas/generate_note_async_failed", "transcribe_async.succeeded": "#/components/schemas/transcribe_async_succeeded", "transcribe_async.failed": "#/components/schemas/transcribe_async_failed", "dictate_async.succeeded": "#/components/schemas/dictate_async_succeeded", "dictate_async.failed": "#/components/schemas/dictate_async_failed" } }, "example": { "id": "0cf0b04d-5bbe-47a9-9601-3dd037644f65", "created_at": "2024-07-15T12:47:34.380Z", "type": "generate_note_async.succeeded", "data": { "id": "51abd747-ab5b-4b61-8f28-5a41b554bd7a", "created_at": "2024-07-15T12:47:34.380Z", "type": "generate_note_async.succeeded", "data": { "id": "ec546a5a-37ec-40da-b719-127366072fdc", "client_request_id": "notegen_n123456789", "status": "succeeded", "payload": { "note": { "title": "Fatigue and headache", "sections": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "- Persistent fatigue\n- Mild headaches on the right side" }, { "key": "PAST_MEDICAL_HISTORY", "title": "Past medical history", "text": "- Hypertension\n- Elevated blood sugar levels" }, { "key": "LAB_RESULTS", "title": "Lab results", "text": "- Blood sugar level: 1.4 g/L\n- LDL cholesterol: 2 g/L" } ] } } } } } } }, "parameters": { "async_request_id": { "name": "id", "description": "The id of the asynchronous request.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/uuid" }, "example": "23A9981B-9E46-4ADB-BB0B-8E406C624540" }, "cursor": { "name": "cursor", "description": "The cursor you received in the next_cursor field to fetch the next page.", "in": "query", "required": false, "schema": { "type": "string" } }, "limit": { "name": "limit", "description": "The amount of objects to retrieve, between 1 and 100.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 } }, "order": { "name": "order", "description": "This flag is used to get results sorted in ascending or descending order.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "example": "DESC", "default": "ASC" } }, "user_id": { "name": "user_id", "description": "The unique identifier of the user.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/uuid" } } } } }