> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medisync.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Regenerate Notes

> Regenerate an appointment's notes from its transcription

## Overview

Regenerate the clinical notes for an appointment from its existing transcription. MediSync generates fresh notes and a summary using the requested template and language, updates the stored notes document, and records the chosen template and language on the appointment.

The appointment must already have a transcription; if none exists the request returns `404 Transcription not found`.

<Note>
  This operation is scoped to the owning doctor. The appointment identified by `{id}` must belong to the authenticated user. A request for an appointment you do not own returns `403 Forbidden`, and an unknown appointment returns `404 Appointment not found`.
</Note>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authenticated access. The doctor (user) identity is taken from the JWT.

  ```
  Authorization: Bearer your_jwt_token_here
  ```
</ParamField>

A missing or invalid token returns `401` with a `message` field. See [Error Responses](#error-responses).

## Path Parameters

<ParamField path="id" type="string" required>
  Appointment ID (MongoDB ObjectId, 24 hex characters) to regenerate notes for. Must be owned by the authenticated doctor and have an existing transcription.
</ParamField>

## Body Parameters

<ParamField body="notes_template_type" type="string" required>
  Identifier of the template to generate against — the ID of a Template document. Omitting it returns `400`. A value that is not a valid template ID returns `500` with `Template not found in database.`
</ParamField>

<ParamField body="language" type="string">
  ISO language code for generation (for example `de` or `en`). Falls back to the appointment's stored language when omitted.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the operation succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  The regenerated notes content.

  <Expandable title="data properties">
    <ResponseField name="notes" type="string">
      The newly generated clinical notes content.
    </ResponseField>

    <ResponseField name="summary" type="string">
      The newly generated summary.
    </ResponseField>

    <ResponseField name="citations" type="array">
      Citation objects, or `null` when none are present.
    </ResponseField>

    <ResponseField name="deltas" type="array">
      Change entries, or `null` when not applicable.
    </ResponseField>

    <ResponseField name="changes_summary" type="string">
      Summary of changes, or `null` when not applicable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message (only present when `success` is `false`).
</ResponseField>

<Note>
  Additional fields may be present in the response and should be treated as opaque.
</Note>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.medisync.me/api/notes/regenerate-notes/664e0b1f7c2a5e0011fa9911' \
    -H 'Authorization: Bearer your_jwt_token_here' \
    -H 'Content-Type: application/json' \
    -d '{
      "notes_template_type": "6650a2f19b1e8a0012ab7788",
      "language": "en"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.medisync.me/api/notes/regenerate-notes/664e0b1f7c2a5e0011fa9911',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your_jwt_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        notes_template_type: '6650a2f19b1e8a0012ab7788',
        language: 'en'
      })
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.medisync.me/api/notes/regenerate-notes/664e0b1f7c2a5e0011fa9911',
      headers={
          'Authorization': 'Bearer your_jwt_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'notes_template_type': '6650a2f19b1e8a0012ab7788',
          'language': 'en'
      }
  )

  result = response.json()
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "notes": "S: Patient reports chest pain on exertion, denies dyspnea.\nO: VS stable, HR 72, BP 120/80; EKG normal.\nA: Atypical chest pain, likely musculoskeletal.\nP: Continue monitoring, follow up in 1 week.",
      "summary": "Chest pain evaluation with normal findings - continue monitoring",
      "citations": null,
      "deltas": null,
      "changes_summary": null
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Missing required field theme={null}
  {
    "success": false,
    "error": "Missing appointmentId or notes_template_type"
  }
  ```

  ```json 401 Unauthorized (missing/invalid token) theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```

  ```json 401 Unauthorized (session revoked) theme={null}
  {
    "success": false,
    "message": "Session ended on this device because you signed in elsewhere.",
    "code": "SESSION_REVOKED"
  }
  ```

  ```json 403 Forbidden (not appointment owner) theme={null}
  {
    "success": false,
    "error": "Forbidden"
  }
  ```

  ```json 404 Appointment not found theme={null}
  {
    "success": false,
    "error": "Appointment not found"
  }
  ```

  ```json 404 Transcription not found theme={null}
  {
    "success": false,
    "error": "Transcription not found"
  }
  ```

  ```json 500 Generation/DB failure theme={null}
  {
    "success": false,
    "error": "Failed to regenerate notes and update database"
  }
  ```

  ```json 500 Template not found theme={null}
  {
    "success": false,
    "error": "Template not found in database."
  }
  ```
</ResponseExample>

## Behavior Notes

* **Order of checks**: The request is validated (`400` if `notes_template_type` is missing), then the appointment is loaded (`404` / `403`), then its transcription is loaded (`404`), then notes are generated.
* **Language fallback**: When `language` is omitted, the appointment's stored language is used.
* **Appointment update**: On success the appointment's stored template and language are updated to match the request.
* **Real-time updates**: A real-time note update is emitted to connected clients on success.

## Status Codes

* **200** — Notes regenerated successfully.
* **400** — Missing `notes_template_type`.
* **401** — Missing, invalid, or revoked authentication token.
* **403** — Authenticated user does not own the appointment.
* **404** — Appointment or transcription not found.
* **500** — Generation failure, database update failure, or an invalid template ID.