# 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[​](#determine-your-current-version "Direct link to Determine your current version")

To determine which API version you are currently targeting, please refer to [Targeting a specific version](/2025-05-21/guides/api-versioning/usage.md). 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`[​](#upgrade-to-the-latest-version-before-2024-10-01 "Direct link to 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`.

## Use an OAuth Client instead of Server Keys[​](#use-an-oauth-client-instead-of-server-keys "Direct link to 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](https://oauth.net/private-key-jwt/) standard for higher security.

Please check the dedicated [OAuth Client authentication](/2025-05-21/guides/authentication.md) page for details on how to start using this new authentication flow.

## Change your base URL[​](#change-your-base-url "Direct link to Change your base URL")

### Product name change[​](#product-name-change "Direct link to 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-your-region "Direct link to 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[​](#new-locales "Direct link to 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-response-flow "Direct link to 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](/2025-05-21/guides/best-practices/asynchronous-note-generation.md) guide for more details.

## Each old endpoint's migration[​](#each-old-endpoints-migration "Direct link to Each old endpoint's migration")

### Create or update a user: `/users`[​](#create-or-update-a-user-users "Direct link to 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`[​](#create-read-update-or-delete-dot-phrases-dot_phrases "Direct link to 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`[​](#listen-websocket-listen-ws "Direct link to 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](#new-locales) above).

  * Example:

    <!-- -->

    | 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" } ] }
    ``` |

* 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[​](#listen-from-audio-file "Direct link to 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[​](#changes-common-to-both-sync--async-listen-endpoints "Direct link to Changes common to both sync & async Listen endpoints")

* Removed `output_objects` field.
* Field `language` replaced by `speech_locale` (see [New locales](#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[​](#changes-specific-to-the-asynchronous-transcription "Direct link to Changes specific to the asynchronous transcription")

* Field `callback_url` removed.
* Check the [Asynchronous requests response flow](#asynchronous-requests-response-flow) for how to migrate your usage of `callback_url`.

### Note generation endpoints[​](#note-generation-endpoints "Direct link to 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[​](#changes-common-to-both-sync--async-note-generation-endpoints "Direct link to Changes common to both sync & async note generation endpoints")

* Removed `output_objects` field.

* Field `language` replaced by `note_locale` (see [New locales](#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](/2025-05-21/guides/note-templates/note-customization.md) 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](/2025-05-21/guides/note-templates/note-templates-sections.md).

| 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"
  }
]
}
``` |

#### Changes specific to the asynchronous note generation[​](#changes-specific-to-the-asynchronous-note-generation "Direct link to Changes specific to the asynchronous note generation")

* Field `callback_url` removed.
* Check the [Asynchronous requests response flow](#asynchronous-requests-response-flow) for how to migrate your usage of `callback_url`.

### Generate normalized data endpoint[​](#generate-normalized-data-endpoint "Direct link to 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](#new-locales).
* Changes to the input `note` as per the changes to the generated note, see [Note generation endpoints](#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[​](#generate-patient-instructions-endpoint "Direct link to 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](#new-locales).
* Changes to `instructions_locale` field as per speech locale in [New locales](#new-locales).
* Changes to the input `note` as per the changes to the generated note, see [Note generation endpoints](#note-generation-endpoints).