> ## 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.

# Create Transcription

> Create the transcription for a specific appointment.

## Overview

Creates the transcription for a specific appointment. The transcription is stored as an ordered array of transcript segments, the appointment is advanced through its processing workflow, and clinical note generation is triggered automatically.

Only one transcription may exist per appointment. If a transcription already exists, the request is rejected.

<Warning>
  Only one transcription can be created per appointment. If a transcription already exists, the request is rejected with `Transcription already exists`.
</Warning>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer JWT token. The calling user is derived from the token; there is no `uid` parameter.

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

## Path Parameters

<ParamField path="appointmentId" type="string" required>
  The appointment ObjectId this transcription belongs to. Only one transcription may exist per appointment.

  ```
  665f8a1b2c3d4e5f6789012f3
  ```
</ParamField>

## Body Parameters

<ParamField body="transcription" type="array" required>
  Ordered array of transcript segment objects. Each segment is an object such as `{ "sender": "speaker_0", "message": "...", "start_time": "00:00:05,800" }`, where `sender` is a diarization speaker label and `start_time` is an SRT-style timestamp string. The value is stored as-is; a non-array value is rejected by validation (`500`).
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the transcription was created successfully.
</ResponseField>

<ResponseField name="data" type="object">
  The created transcription record.

  <Expandable title="Transcription Object">
    <ResponseField name="_id" type="string">
      Unique transcription identifier.
    </ResponseField>

    <ResponseField name="appointment_id" type="string">
      The associated appointment ObjectId.
    </ResponseField>

    <ResponseField name="transcription" type="array">
      Ordered array of transcript segment objects, exactly as stored.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Creation timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last-update timestamp (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Additional fields (for example `__v`) may appear on the transcription object. Treat any field not documented here as opaque.
</Info>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.medisync.me/api/transcriptions/add/665f8a1b2c3d4e5f6789012f3' \
    -H 'Authorization: Bearer <JWT>' \
    -H 'Content-Type: application/json' \
    -d '{
      "transcription": [
        { "sender": "speaker_0", "message": "Guten Tag, was fuehrt Sie zu mir?", "start_time": "00:00:01,200" },
        { "sender": "speaker_1", "message": "Ich habe seit heute Morgen Brustschmerzen.", "start_time": "00:00:05,800" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.medisync.me/api/transcriptions/add/665f8a1b2c3d4e5f6789012f3',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer <JWT>',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        transcription: [
          { sender: 'speaker_0', message: 'Guten Tag, was fuehrt Sie zu mir?', start_time: '00:00:01,200' },
          { sender: 'speaker_1', message: 'Ich habe seit heute Morgen Brustschmerzen.', start_time: '00:00:05,800' }
        ]
      })
    }
  );

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

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

  data = {
      "transcription": [
          {"sender": "speaker_0", "message": "Guten Tag, was fuehrt Sie zu mir?", "start_time": "00:00:01,200"},
          {"sender": "speaker_1", "message": "Ich habe seit heute Morgen Brustschmerzen.", "start_time": "00:00:05,800"}
      ]
  }

  headers = {
      'Authorization': 'Bearer <JWT>',
      'Content-Type': 'application/json'
  }

  response = requests.post(
      'https://app.medisync.me/api/transcriptions/add/665f8a1b2c3d4e5f6789012f3',
      headers=headers,
      json=data
  )

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

## Example Response

```json Success (200) theme={null}
{
  "success": true,
  "data": {
    "_id": "665f8a1b2c3d4e5f6789012f7",
    "appointment_id": "665f8a1b2c3d4e5f6789012f3",
    "transcription": [
      { "sender": "speaker_0", "message": "Guten Tag, was fuehrt Sie zu mir?", "start_time": "00:00:01,200" },
      { "sender": "speaker_1", "message": "Ich habe seit heute Morgen Brustschmerzen.", "start_time": "00:00:05,800" }
    ],
    "createdAt": "2026-06-30T10:30:00.000Z",
    "updatedAt": "2026-06-30T10:30:00.000Z"
  }
}
```

## Error Responses

```json 401 Unauthorized theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

```json 400 Transcription Already Exists theme={null}
{
  "success": false,
  "error": "Transcription already exists"
}
```

```json 404 Appointment Not Found After Save theme={null}
{
  "success": false,
  "error": "Associated appointment not found after saving transcription."
}
```

<Note>
  The `Unauthorized` response uses the `message` field; handler-level errors use the `error` field. Unexpected server errors — including posting a non-array `transcription` value, which fails validation — return `500 { "success": false, "error": "<message>" }`.
</Note>

## Behavior Notes

* **One transcription per appointment**: A second create for the same appointment is rejected with `Transcription already exists`.
* **Status advance**: If the appointment status is `transcribing` or `error_transcription`, it is advanced to `processing`.
* **Note generation**: Creating a transcription automatically triggers clinical note generation for the appointment. This runs in the background and does not change the HTTP response.
* **Order preserved**: Segments are stored and returned in the order provided.