# Generate a note asynchronously ``` POST /digest_async ``` Digests a list of transcript items and produces a structured clinical note. ## Request[​](#request "Direct link to Request") * application/json ### Body**required** * **output\_objects**digest\_output\_object (string)\[]required Specifies which items you want us to send you back. In other words, which feature(s) you want to use, for now only note generation is available. **Possible values:** \[`note`] **language**copilot\_language (string)required Language of the given transcript and the desired 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). **Possible values:** \[`fr`, `en`, `en-US`, `en-GB`, `fr-FR`, `es-ES`, `es-MX`] **Example: **`en-US` ******transcript\_items** object\[]required The transcript from which to generate the note. You 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]\(/core-api/reference/2024-04-22/server/copilot-listen-ws) does not guarantee the order. Thus, before calling this note-generation API please \*\*filter-out non-final items and sort them by \`start\_offset\_ms\`\*\*. Array \[ * **text**stringrequired The transcribed text. **Example: **`Also, I’m allergic to peanuts.` **speaker**copilot\_speaker (string)required Who said the text in this transcript item. **Possible values:** \[`doctor`, `patient`, `unspecified`] **Example: **`doctor` ] * **section\_style**copilot\_section\_style (string) Choose a desired style for note sections: • `paragraphs`: Prioritizes generating paragraphs; • `bullet_points`: Prioritizes structuring content using bullet points. • `auto`: Automatically picks the most natural formatting option. Default is `auto`. **Possible values:** \[`auto`, `paragraphs`, `bullet_points`] **Example: **`paragraphs` **split\_by\_problem**copilot\_split\_by\_problem (boolean) Flag to structure the content of the note sections according to distinct clinical problems or topics addressed during the consultation. When this flag is enabled, the text within some sections of the clinical note is organized into subsections, each corresponding to a specific problem or topic. This format aims to enhance the clarity and organization of the clinical note, making it easier to read and understand the different issues discussed during the consultation. **Important**: Currently, the application of this flag is limited to the `HISTORY_OF_PRESENT_ILLNESS` and `SOAP_SUBJECTIVE` sections and is only effective when the language is set to English (US or GB). **Default value: **`false` **note\_template**copilot\_note\_template (string) The template used to generate the note. Some templates are **only available in specific languages**. Check [Note template](/core-api/guides/note-templates-sections-legacy-2024-10-01) for details. **Possible values:** \[`GENERAL_MEDICINE`, `GENERAL_MEDICINE_AP_MERGED`, `CARDIOLOGY`, `PSYCHIATRY`, `DIET`, `PSYCHOLOGY`, `SOAP`, `GENERAL_MEDICINE_WCC`, `SOAP_WCC`, `GENERAL_MEDICINE_EMERGENCY`, `SOAP_EMERGENCY`] **Example: **`GENERAL_MEDICINE` **note** object Optional initial Note to be enhanced using the new \`transcript\_items\`. This is useful if you generate notes gradually to avoid accumulating a very long transcript items list. Typically, this will be the last note Nabla generated for you along with the new \`transcript\_items\` that did not serve for its generation. \*\*Important\*\*: This is expected to be a recent (up to few-hours old) Nabla-generated note. If the note is too old or altered, you will get an error. ******sections** object\[]required Sections of the note. Array \[ * **key**copilot\_note\_section\_key (string)required A key identifying a section of a note. The set of possible keys depend on the template that is used. Check [Note template](/core-api/guides/note-templates-sections-legacy-2024-10-01) for possible values. **Possible values:** \[`ALLERGIES`, `APPOINTMENTS`, `ASSESSMENT`, `ASSESSMENT_AND_PLAN`, `CARDIOVASCULAR_RISKS`, `CHIEF_COMPLAINT`, `CURRENT_MEDICATIONS`, `DIET_APPOINTMENTS`, `DIET_CHIEF_COMPLAINT`, `DIET_HABITS`, `DIET_LIFESTYLE`, `DIET_MEDICAL_HISTORY`, `DIET_OBJECTIVES`, `DIET_VITALS`, `FAMILY_HISTORY`, `HISTORY_OF_PRESENT_ILLNESS`, `IMAGING_RESULTS`, `IMMUNIZATIONS`, `LAB_RESULTS`, `MENTAL_HEALTH_EXAM`, `MENTAL_HEALTH_HISTORY`, `PAST_MEDICAL_HISTORY`, `PAST_OBSTETRIC_HISTORY`, `PAST_SURGICAL_HISTORY`, `PHYSICAL_EXAM`, `PLAN`, `PRESCRIPTION`, `PSYCHOLOGY_HISTORY_OF_COMPLAINT`, `SOAP_ASSESSMENT`, `SOAP_OBJECTIVE`, `SOAP_PLAN`, `SOAP_SUBJECTIVE`, `SOCIAL_HISTORY`, `VITALS`, `WELL_CHILD_CARE`] **Example: **`CHIEF_COMPLAINT` **title**stringrequired The section title. **Example: **`Chief complaint` **text**string Content of the note section (required). **Example: **`Sleep disorder` ] **patient\_context**string Some contextual information that will be used to generate the note (for example name, gender, age, pronouns, medical history) \[BETA]. **Possible values:** `<= 700 characters` **callback\_url**stringrequired Once we are done processing the input and generating the note, we will call you back with a 'POST' on this URL and a Json body respecting exactly the same schema as the response of the synchronous equivalent endpoint (i.e. [`/copilot/digest`](copilot-digest)). **client\_request\_id**copilot\_client\_request\_id (string) 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. *Note*: this id must be different for every request. It is recommended to use a randomly generated UUID. **Possible values:** `<= 128 characters` ## Responses[​](#responses "Direct link to Responses") * 200 * 299 Request received and processing started. * application/json - Schema - Example (from schema) **Schema** * **request\_id**uuidrequired The id of the request you just created. **Example: **`98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6` **client\_request\_id**string The provided `client_request_id`. ``` { "request_id": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "client_request_id": "string" } ``` Here's the schema of the Json payload that will be sent \*\*asynchronously\*\* to the URL you provided. (299 is not a possible response code — only a way here to document the asynchronous payload schema). * application/json - Schema **Schema** * oneOf * success * error **request\_id**uuidrequired The id of the async request. **Example: **`98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6` **client\_request\_id**string The `client_request_id` provided in the request. ******note**objectrequired The generated note. **title**string Title of the note. **Example: **`Fever and strong headache` ******sections**object\[]required Content of the note structured in multiple sections. Array \[ * **key**copilot\_note\_section\_key (string)required A key identifying a section of a note. The set of possible keys depend on the template that is used. Check [Note template](/core-api/guides/note-templates-sections-legacy-2024-10-01) for possible values. **Possible values:** \[`ALLERGIES`, `APPOINTMENTS`, `ASSESSMENT`, `ASSESSMENT_AND_PLAN`, `CARDIOVASCULAR_RISKS`, `CHIEF_COMPLAINT`, `CURRENT_MEDICATIONS`, `DIET_APPOINTMENTS`, `DIET_CHIEF_COMPLAINT`, `DIET_HABITS`, `DIET_LIFESTYLE`, `DIET_MEDICAL_HISTORY`, `DIET_OBJECTIVES`, `DIET_VITALS`, `FAMILY_HISTORY`, `HISTORY_OF_PRESENT_ILLNESS`, `IMAGING_RESULTS`, `IMMUNIZATIONS`, `LAB_RESULTS`, `MENTAL_HEALTH_EXAM`, `MENTAL_HEALTH_HISTORY`, `PAST_MEDICAL_HISTORY`, `PAST_OBSTETRIC_HISTORY`, `PAST_SURGICAL_HISTORY`, `PHYSICAL_EXAM`, `PLAN`, `PRESCRIPTION`, `PSYCHOLOGY_HISTORY_OF_COMPLAINT`, `SOAP_ASSESSMENT`, `SOAP_OBJECTIVE`, `SOAP_PLAN`, `SOAP_SUBJECTIVE`, `SOCIAL_HISTORY`, `VITALS`, `WELL_CHILD_CARE`] **Example: **`CHIEF_COMPLAINT` **title**stringrequired The section title. **Example: **`Chief complaint` **text**stringrequired Content of the note section. **Example: **`Sleep disorder` ] * ******suggested\_dot\_phrases**object\[] A collection of Dot Phrases that were successfully matched to the encounter's transcript, given the Dot Phrases defined on the calling user. Will be null in the context of a Server API call (i.e. no calling user). This functionality enriches the generated note by expanding concise key sentences (triggers) into a more detailed format following the given Dot Phrase definition. Thus, enhancing the depth and utility of the note and facilitating a comprehensive review of patient assessments in a structured and conventional manner. Array \[ * ******dot\_phrase**object Dot phrase, also referred to as EHR (Electronic Health Record) macro, is a concise abbreviation (\`trigger\`) that unfolds into a predefined, extended text (\`replacement\`). **id**uuidrequired Unique identifier of the Dot Phrase. **title**stringrequired A user-friendly title for the Dot Phrase. Does not impact the matching logic. **Example: **`Normal physical exam` **trigger**stringrequired The text which, if present in the transcript, will prompt the suggestion of this Dot Phrase. **Example: **`Your physical exam is normal` **content\_auto\_update\_enabled**booleanrequired If true, whenever this dot phrase is suggested, the replacement text will be automatically updated based on the encounter discussion. **Example: **`false` **replacement**stringrequired The replacement text for this Dot Phrase. If the Dot Phrase's trigger is detected, this text will be suggested in the note generation's response. **Example: **`- Heart Examination: Normal, with regular rate and rhythm, no murmurs. - Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi. - Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.` ******note\_section**object **key**copilot\_note\_section\_key (string)required A key identifying a section of a note. The set of possible keys depend on the template that is used. Check [Note template](/core-api/guides/note-templates-sections-legacy-2024-10-01) for possible values. **Possible values:** \[`ALLERGIES`, `APPOINTMENTS`, `ASSESSMENT`, `ASSESSMENT_AND_PLAN`, `CARDIOVASCULAR_RISKS`, `CHIEF_COMPLAINT`, `CURRENT_MEDICATIONS`, `DIET_APPOINTMENTS`, `DIET_CHIEF_COMPLAINT`, `DIET_HABITS`, `DIET_LIFESTYLE`, `DIET_MEDICAL_HISTORY`, `DIET_OBJECTIVES`, `DIET_VITALS`, `FAMILY_HISTORY`, `HISTORY_OF_PRESENT_ILLNESS`, `IMAGING_RESULTS`, `IMMUNIZATIONS`, `LAB_RESULTS`, `MENTAL_HEALTH_EXAM`, `MENTAL_HEALTH_HISTORY`, `PAST_MEDICAL_HISTORY`, `PAST_OBSTETRIC_HISTORY`, `PAST_SURGICAL_HISTORY`, `PHYSICAL_EXAM`, `PLAN`, `PRESCRIPTION`, `PSYCHOLOGY_HISTORY_OF_COMPLAINT`, `SOAP_ASSESSMENT`, `SOAP_OBJECTIVE`, `SOAP_PLAN`, `SOAP_SUBJECTIVE`, `SOCIAL_HISTORY`, `VITALS`, `WELL_CHILD_CARE`] **Example: **`CHIEF_COMPLAINT` **title**stringrequired Section title. **Example: **`Assessment & Plan.` **text\_to\_insert**stringrequired The actual suggested content, to be inserted in the corresponding note section. Please note that the content might be different from the replacement in the original Dot Phrase definition. In fact, the `text_to_insert` takes into account the contextual information of the encounter and might change the original Dot Phrase replacement text, for instance to include exceptions. **Example: **`- Heart Examination: Normal, with regular rate and rhythm, no murmurs. - Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi. - Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.` ] **request\_id**uuidrequired The id of the async request. **Example: **`98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6` **client\_request\_id**string The `client_request_id` provided in the request. **error\_code**integerrequired **Example: **`422` **error\_message**string **Example: **`We can't generate the note when the transcript is too short.` ## Operation spec ```json { "method": "post", "path": "/digest_async", "operationId": "copilot-digest-async", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The object containing the information needed to generate a note.", "properties": { "output_objects": { "type": "array", "description": "Specifies which items you want us to send you back. In other words, which feature(s) you want to use, for now only note generation is available.", "items": { "type": "string", "description": "Specifies which items you want us to send you back.", "enum": [ "note" ], "example": "note", "title": "digest_output_object" } }, "language": { "description": "Language of the given transcript and the desired 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).", "type": "string", "enum": [ "fr", "en", "en-US", "en-GB", "fr-FR", "es-ES", "es-MX" ], "example": "en-US", "title": "copilot_language" }, "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](/server/copilot-listen-ws) does not guarantee the order. Thus, before calling this note-generation API please **filter-out non-final items and sort them by `start_offset_ms`**.", "items": { "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": "string", "enum": [ "doctor", "patient", "unspecified" ], "description": "Who said the text in this transcript item.", "example": "doctor", "title": "copilot_speaker" } }, "required": [ "text", "speaker" ], "title": "copilot_transcript_item_request" } }, "section_style": { "type": "string", "enum": [ "auto", "paragraphs", "bullet_points" ], "description": "Choose a desired style for note sections:\n\n • `paragraphs`: 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`.", "example": "paragraphs", "title": "copilot_section_style" }, "split_by_problem": { "type": "boolean", "default": false, "description": "Flag to structure the content of the note sections according to distinct clinical problems or topics addressed during the consultation.\n\nWhen this flag is enabled, the text within some sections of the clinical note is organized into subsections, each corresponding to a specific problem or topic. This format aims to enhance the clarity and organization of the clinical note, making it easier to read and understand the different issues discussed during the consultation.\n\n**Important**: Currently, the application of this flag is limited to the `HISTORY_OF_PRESENT_ILLNESS` and `SOAP_SUBJECTIVE` sections and is only effective when the language is set to English (US or GB).", "title": "copilot_split_by_problem" }, "note_template": { "type": "string", "enum": [ "GENERAL_MEDICINE", "GENERAL_MEDICINE_AP_MERGED", "CARDIOLOGY", "PSYCHIATRY", "DIET", "PSYCHOLOGY", "SOAP", "GENERAL_MEDICINE_WCC", "SOAP_WCC", "GENERAL_MEDICINE_EMERGENCY", "SOAP_EMERGENCY" ], "description": "The desired template of the generated note.\n\nSome templates are **only available in specific languages**. Check [Note template](/guides/note-templates-sections) for details.", "example": "GENERAL_MEDICINE", "title": "copilot_note_template" }, "note": { "description": "Optional initial Note to be enhanced using the new `transcript_items`.\nThis is useful if you generate notes gradually to avoid accumulating a very long transcript items list.\nTypically, this will be the last note Nabla generated for you along with the new `transcript_items` that did not serve for its generation.\n**Important**: This is expected to be a recent (up to few-hours old) Nabla-generated note. If the note is too old or altered, you will get an error.", "type": "object", "properties": { "sections": { "type": "array", "description": "Sections of the note.", "items": { "type": "object", "description": "A note section.", "properties": { "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](/guides/note-templates-sections) for possible values.", "example": "CHIEF_COMPLAINT", "enum": [ "ALLERGIES", "APPOINTMENTS", "ASSESSMENT", "ASSESSMENT_AND_PLAN", "CARDIOVASCULAR_RISKS", "CHIEF_COMPLAINT", "CURRENT_MEDICATIONS", "DIET_APPOINTMENTS", "DIET_CHIEF_COMPLAINT", "DIET_HABITS", "DIET_LIFESTYLE", "DIET_MEDICAL_HISTORY", "DIET_OBJECTIVES", "DIET_VITALS", "FAMILY_HISTORY", "HISTORY_OF_PRESENT_ILLNESS", "IMAGING_RESULTS", "IMMUNIZATIONS", "LAB_RESULTS", "MENTAL_HEALTH_EXAM", "MENTAL_HEALTH_HISTORY", "PAST_MEDICAL_HISTORY", "PAST_OBSTETRIC_HISTORY", "PAST_SURGICAL_HISTORY", "PHYSICAL_EXAM", "PLAN", "PRESCRIPTION", "PSYCHOLOGY_HISTORY_OF_COMPLAINT", "SOAP_ASSESSMENT", "SOAP_OBJECTIVE", "SOAP_PLAN", "SOAP_SUBJECTIVE", "SOCIAL_HISTORY", "VITALS", "WELL_CHILD_CARE" ], "title": "copilot_note_section_key" }, "title": { "type": "string", "description": "The section title.", "example": "Chief complaint" }, "text": { "type": "string", "description": "Content of the note section (required).", "example": "Sleep disorder" } }, "required": [ "key", "title" ], "title": "copilot_note_section_request" } } }, "required": [ "sections" ], "title": "copilot_note_request" }, "patient_context": { "type": "string", "description": "Some contextual information that will be used to generate the note (for example name, gender, age, pronouns, medical history) [BETA].", "maxLength": 700 } }, "required": [ "output_objects", "transcript_items", "language" ], "title": "digest_request" }, { "type": "object", "properties": { "callback_url": { "type": "string", "description": "Once we are done processing the input and generating the note, we will call you back with a 'POST' on this URL and a Json body respecting exactly the same schema as the response of the synchronous equivalent endpoint (i.e. [`/copilot/digest`](copilot-digest))." }, "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.", "title": "copilot_client_request_id" } }, "required": [ "callback_url" ] } ], "title": "digest_async_request" } } } }, "responses": { "200": { "description": "Request received and processing started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "description": "The id of the request you just created.", "type": "string", "format": "uuid", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "title": "uuid" }, "client_request_id": { "type": "string", "description": "The provided `client_request_id`." } }, "required": [ "request_id" ] } } } }, "299": { "description": "Here's the schema of the Json payload that will be sent **asynchronously** to the URL you provided.\n(299 is not a possible response code — only a way here to document the asynchronous payload schema).", "content": { "application/json": { "schema": { "oneOf": [ { "title": "success" }, { "title": "error" } ], "title": "digest_response_async" } } } } } } ```