Generate a note asynchronously
POST/generate-note-async
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.
Request
Responses
- 200
Request received and processing started.
Operation spec
{
"method": "post",
"path": "/generate-note-async",
"operationId": "generate-note-async",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"description": "Input for note generation.",
"properties": {
"note_locale": {
"type": "string",
"description": "Locale of the note.",
"enum": [
"ENGLISH_US",
"ENGLISH_UK",
"FRENCH_FR"
],
"example": "ENGLISH_US",
"title": "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](/core-api/reference/2025-01-07/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": {
"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": {
"type": "string",
"enum": [
"DOCTOR",
"PATIENT",
"UNSPECIFIED"
],
"description": "Who said the text in this transcript item.",
"example": "DOCTOR",
"title": "speaker"
}
},
"required": [
"text",
"speaker_type"
],
"title": "transcript_item_request"
}
},
"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 used to generate the note.\n\nSome templates are **only available in specific languages**. Check [Note template](/core-api/guides/note-templates/note-templates-sections) for details.",
"example": "GENERIC_MULTIPLE_SECTIONS",
"title": "note_template"
},
"note_sections_customization": {
"type": "array",
"items": {
"type": "object",
"properties": {
"section_key": {
"type": "string",
"title": "note_section_key",
"description": "Key of the note section this customization should apply to.",
"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"
]
},
"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.",
"title": "note_section_customization_custom_instruction"
},
"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`.",
"title": "note_section_customization_section_style"
},
"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.",
"title": "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"
],
"title": "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](/core-api/guides/note-templates/note-customization) for compatibility matrix."
},
"previous_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.",
"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": {
"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](/core-api/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"
],
"title": "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"
],
"title": "note_section_request"
}
}
},
"required": [
"sections"
],
"title": "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": [
"transcript_items",
"note_locale"
],
"title": "generate_note_request"
},
{
"type": "object",
"properties": {
"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": "client_request_id"
}
}
}
],
"title": "generate_note_async_request"
}
}
}
},
"responses": {
"200": {
"description": "Request received and processing started.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "ONGOING",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
]
},
{
"title": "FAILED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"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"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
]
},
{
"title": "SUCCEEDED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The generated note.",
"required": [
"note"
],
"properties": {
"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": {
"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](/core-api/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"
],
"title": "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"
}
],
"title": "note_section"
}
}
},
"required": [
"sections"
],
"title": "note"
},
"suggested_dot_phrases": {
"type": "string"
}
},
"title": "async_note_generation_succeeded_payload"
}
},
"required": [
"id",
"status"
]
}
],
"discriminator": {
"propertyName": "status",
"mapping": {
"ONGOING": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
],
"title": "async_request_ongoing"
},
"FAILED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"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"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
],
"title": "async_request_failed"
},
"SUCCEEDED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"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": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The generated note.",
"required": [
"note"
],
"properties": {
"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": {
"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](/core-api/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"
],
"title": "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"
}
],
"title": "note_section"
}
}
},
"required": [
"sections"
],
"title": "note"
},
"suggested_dot_phrases": {
"type": "string"
}
},
"title": "async_note_generation_succeeded_payload"
}
},
"required": [
"id",
"status"
],
"title": "async_note_generation_succeeded"
}
}
},
"title": "async_note_generation"
}
}
}
}
}
}