Migrating from API versions prior to 2024-10-01

The Nabla Core API version 2024-10-01 introduces many new features and structural changes. This step-by-step guide will help you migrate your existing integration to the latest version, enabling you to fully utilize the Nabla Core API.

Determine your current version

To determine which API version you are currently targeting, please refer to Targeting a specific version. You might be either explicitly specifying an API version for all your calls or relying on the pinned version set in the API Admin Console.

During the migration, we recommend to use the explicit version header for new migrated API calls to target the newer version. Once all your clients are migrated you can go upgrade the pinned version in the API Admin Console.

Upgrade to the latest version before `2024-10-01`

This guide details migration from the latest version prior to 2024-10-01, i.e. version 2024-04-22.

If your API version is older than 2024-04-22, please upgrade to 2024-04-22 first by following the instructions on the archived Upgrades page before proceeding with this guide.

Use an OAuth Client instead of Server Keys

Starting with version 2024-10-01, the long-lived Server Keys will no longer be accepted for Server API authentication. The new flow for authenticating your server calls is now based on OAuth Private Key JWT standard for higher security.

Please check the dedicated OAuth Client authentication page for details on how to start using this new authentication flow.

Change your base URL

Product name change

Apply the following renaming to the base URL:

/v1/copilot-api/server become /v1/core/server
/v1/copilot-api/user become /v1/core/user

Specify your region

Specify the region on which your Nabla Core API organization is hosted, us for the United States and eu for European Union.

https://us.api.nabla.com/v1/core + (/server or /user) + /path/to/endpoint
https://eu.api.nabla.com/v1/core + (/server or /user) + /path/to/endpoint

New locales

Instead of a single enum, we now have two separate enums for languages, henceforth called locales:

Speech locale: Supports 35 values for various languages with regional dialects and variations. Used for transcription (speech-to-text) and generated patient instructions.
Note locale: Supports 3 values, i.e. ENGLISH_US, ENGLISH_UK and FRENCH_FR, used for generated notes.

Asynchronous requests response flow

Asynchronous requests, such as /digest_async and /listen_async used to take a callback_url to which the response was sent in an HTTP POST call.

This behavior is deprecated and replaced by a polling mechanism, along with an alternative webhook mechanism.

Please refer to the Asynchronous note generation guide for more details.

Each old endpoint's migration

Create or update a user: `/users`

Remove email and roles fields from both input and output, those fields were already deprecated.

Create, read, update or delete dot phrases: `/dot_phrases`

Endpoints case changed from snake to kebab: /dot_phrases becomes /dot-phrases.

Listen websocket `/listen-ws`

Endpoint renamed to /transcribe-ws.
Protocol renamed to transcribe-protocol.
Removed output_objects input field (if you need to filter out frames, this should be done client-side).
Polymorphism discriminator field key in all frames (both input and output frames) renamed from object to type.
Enums values now follow SCREAMING_SNAKE_CASE, e.g. pcm_s16le becomes PCM_S16LE and patient becomes PATIENT.

Changes specific to the Configuration frame:

Discriminator value renamed from listen_config to CONFIG.
Field language replaced by speech_locale (see New locales above).

Example:

Before After

Before	After
`{ "object": "listen_config", "output_objects": ["transcript_item"], "encoding": "pcm_s16le", "sample_rate": 16000, "language": "en-US", "streams": [ { "id": "doctor_stream", "speaker_type": "doctor" } ] }`	`{ "type": "CONFIG", "encoding": "PCM_S16LE", "sample_rate": 16000, "speech_locale": "ENGLISH_US", "streams": [ { "id": "doctor_stream", "speaker_type": "DOCTOR" } ] }`

{
  "object": "listen_config",
  "output_objects": ["transcript_item"],
  "encoding": "pcm_s16le",
  "sample_rate": 16000,
  "language": "en-US",
  "streams": [
    {
      "id": "doctor_stream",
      "speaker_type": "doctor"
    }
  ]
}

{
  "type": "CONFIG",
  "encoding": "PCM_S16LE",
  "sample_rate": 16000,
  "speech_locale": "ENGLISH_US",
  "streams": [
    {
      "id": "doctor_stream",
      "speaker_type": "DOCTOR"
    }
  ]
}

Changes specific to the Transcript item frame:
- Field speaker renamed to speaker_type.
No particular changes other than those mentioned above for the frames: Audio chunk, End, Audio chunk ack, and error message.

Listen from audio file

Previously known as /listen, it's now called /transcribe.
Previously known as /listen_async, it's now called /transcribe-async.

Changes common to both sync & async Listen endpoints

Removed output_objects field.
Field language replaced by speech_locale (see New locales above).
In output (response) schema: Field speaker (inside transcript[]) renamed to speaker_type.
Removed note generation capability. The Transcribe endpoint is only meant for transcription. You should combine with dedicated note generation endpoints if needed.
Note generation related fields removed: section_style, split_by_problem and note_template.

Changes specific to the asynchronous transcription

Field callback_url removed.
Check the Asynchronous requests response flow for how to migrate your usage of callback_url.

Note generation endpoints

Previously known as /digest, it's now called /generate-note.
Previously known as /digest_async, it's now called /generate-note-async.

Changes common to both sync & async note generation endpoints

Removed output_objects field.
Field language replaced by note_locale (see New locales above).
In transcript_items schema: Field speaker renamed to speaker_type.
Field note renamed to previous_note.
- You can also specify an optional title field (note title), as it might have been generated by Nabla.
Fields section_style and split_by_problem removed, to be replaced by per-section customization capabilities that offer more and finer customization options.
- Please notice that the value PARAGRAPHS from section_style enum maps to the singular PARAGRAPH (without an S).
Field note_template enum values changed, here's a mapping:
- GENERAL_MEDICINE becomes GENERIC_MULTIPLE_SECTIONS.
- GENERAL_MEDICINE_AP_MERGED becomes GENERIC_MULTIPLE_SECTIONS_AP_MERGED.
- SOAP becomes GENERIC_SOAP.
- GENERAL_MEDICINE_WCC becomes WCC_MULTIPLE_SECTIONS.
- SOAP_WCC becomes WCC_SOAP.
- GENERAL_MEDICINE_EMERGENCY becomes EMERGENCY_MULTIPLE_SECTIONS.
- SOAP_EMERGENCY becomes EMERGENCY_SOAP.
- CARDIOLOGY becomes CARDIOLOGY_MULTIPLE_SECTIONS.
- PSYCHIATRY becomes PSYCHIATRY_MULTIPLE_SECTIONS.
- DIET becomes DIET_MULTIPLE_SECTIONS.
- PSYCHOLOGY becomes PSYCHOLOGY_MULTIPLE_SECTIONS.
Generated note sections keys (e.g. note.sections[].key) enum values changed, here's a mapping:
- SOAP_SUBJECTIVE (Subjective) becomes SUBJECTIVE.
- SOAP_OBJECTIVE (Objective) becomes OBJECTIVE.
- SOAP_ASSESSMENT (Assessment) becomes ASSESSMENT.
- SOAP_PLAN (Plan) becomes PLAN.
- SOAP_ASSESSMENT_AND_PLAN (Assessment & Plan) becomes ASSESSMENT_AND_PLAN.
- SOAP_DIAGNOSTIC_TESTS_ORDERED (Diagnostic tests ordered) becomes DIAGNOSTIC_TESTS_ORDERED.
- DIET_LIFESTYLE (Lifestyle) becomes LIFESTYLE.
- DIET_MEDICAL_HISTORY (Medical history) becomes PAST_MEDICAL_HISTORY.
- DIET_CHIEF_COMPLAINT (Reason for visit and goals) becomes CHIEF_COMPLAINT.
- DIET_VITALS (Vitals) becomes VITALS.
- DIET_HABITS (Food habits) becomes FOOD_HABITS.
- DIET_OBJECTIVES (Objectives and advice) becomes OBJECTIVES_AND_ADVICE.
- DIET_APPOINTMENTS (Appointment) becomes APPOINTMENTS.
- PSYCHOLOGY_HISTORY_OF_COMPLAINT (History of the present complaint) becomes HISTORY_OF_PRESENT_COMPLAINT.
- CARDIOVASCULAR_RISKS (Cardiovascular risk factors) becomes CARDIOVASCULAR_RISK_FACTORS.
Check the new templates and their sections in Note templates and sections.

Before After

Before	After
`{ "output_objects": ["note"], "language": "en-US", "note_template": "GENERAL_MEDICINE", "section_style": "paragraphs", "split_by_problem": true, "patient_context": "43 y.o. with Diabetes", "note": { "sections": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "Fatigue and headache" } ] }, "transcript_items": [ { "text": "Also, I’m allergic to peanuts.", "speaker": "patient" } ] }`	{ "note_locale": "ENGLISH_US", "note_template": "GENERIC_MULTIPLE_SECTIONS", "patient_context": "43 y.o. with Diabetes", "note_sections_customization": [ { "section_key": "HISTORY_OF_PRESENT_ILLNESS", "level_of_detail": "DETAILED", "split_by_problem": true }, { "section_key": "VITALS", "style": "BULLET_POINTS" }, { "section_key": "ALLERGIES", "style": "PARAGRAPH" } ], "previous_note": { "title": "Fatigue", "sections": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "Fatigue and headache" } ] }, "transcript_items": [ { "text": "Also, I’m allergic to peanuts.", "speaker_type": "patient" } ] }

{
  "output_objects": ["note"],
  "language": "en-US",
  "note_template": "GENERAL_MEDICINE",
  "section_style": "paragraphs",
  "split_by_problem": true,
  "patient_context": "43 y.o. with Diabetes",
  "note": {
    "sections": [
      {
        "key": "CHIEF_COMPLAINT",
        "title": "Chief complaint",
        "text": "Fatigue and headache"
      }
    ]
  },
  "transcript_items": [
    {
      "text": "Also, I’m allergic to peanuts.",
      "speaker": "patient"
    }
  ]
}

{
  "note_locale": "ENGLISH_US",
  "note_template": "GENERIC_MULTIPLE_SECTIONS",
  "patient_context": "43 y.o. with Diabetes",
  "note_sections_customization": [
    {
      "section_key": "HISTORY_OF_PRESENT_ILLNESS",
      "level_of_detail": "DETAILED",
      "split_by_problem": true
    },
    { "section_key": "VITALS", "style": "BULLET_POINTS" },
    { "section_key": "ALLERGIES", "style": "PARAGRAPH" }
  ],
  "previous_note": {
    "title": "Fatigue",
    "sections": [
      {
        "key": "CHIEF_COMPLAINT",
        "title": "Chief complaint",
        "text": "Fatigue and headache"
      }
    ]
  },
  "transcript_items": [
    {
      "text": "Also, I’m allergic to peanuts.",
      "speaker_type": "patient"
    }
  ]
}

Changes specific to the asynchronous note generation

Field callback_url removed.
Check the Asynchronous requests response flow for how to migrate your usage of callback_url.

Generate normalized data endpoint

Replace the path /generate_normalized_data with /generate-normalized-data (case change).
New required input field: note_template.
Changes to note_locale field as per New locales.
Changes to the input note as per the changes to the generated note, see Note generation endpoints.
Enums values for FHIR condition clinical status and FHIR condition category now follow SCREAMING_SNAKE_CASE, e.g. value resolved becomes RESOLVED and encounter_diagnosis becomes ENCOUNTER_DIAGNOSIS.

Generate patient instructions endpoint

Replace the path /generate_patient_instructions with /generate-patient-instructions (case change).
New required input field: note_template.
Changes to note_locale field as per note locale in New locales.
Changes to instructions_locale field as per speech locale in New locales.
Changes to the input note as per the changes to the generated note, see Note generation endpoints.

Determine your current version​

Upgrade to the latest version before 2024-10-01​

Use an OAuth Client instead of Server Keys​

Change your base URL​

Product name change​

Specify your region​

New locales​

Asynchronous requests response flow​

Each old endpoint's migration​

Create or update a user: /users​

Create, read, update or delete dot phrases: /dot_phrases​

Listen websocket /listen-ws​

Listen from audio file​

Changes common to both sync & async Listen endpoints​

Changes specific to the asynchronous transcription​

Note generation endpoints​

Changes common to both sync & async note generation endpoints​

Changes specific to the asynchronous note generation​

Generate normalized data endpoint​

Generate patient instructions endpoint​