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

# Quickstart

> Go from authentication to AI-generated clinical notes with the MediSync Dashboard API in a few steps

## Welcome to the MediSync API

MediSync provides APIs for medical AI, transcription, and healthcare data management. This guide walks you through a first integration with the **Dashboard API**: authenticate, create an appointment, attach a recording, and retrieve the AI-generated transcription and clinical notes.

## Prerequisites

<AccordionGroup>
  <Accordion icon="user-check" title="MediSync account">
    Sign up for a MediSync account at [app.medisync.me](https://app.medisync.me/register). You'll authenticate with your professional email and password.
  </Accordion>

  <Accordion icon="credit-card" title="Active subscription (some features)">
    Creating appointments and generating AI notes require an active subscription or trial. New accounts start on a trial; check your status in the dashboard.
  </Accordion>
</AccordionGroup>

## Step 1: Authenticate

Authenticate with your MediSync credentials to obtain a JWT token:

```bash theme={null}
curl -X POST https://app.medisync.me/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@example.com",
    "password": "your_password",
    "remember": false
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "uid": "6578a1b2c3d4e5f601234567",
  "userTitle": "Dr.",
  "firstName": "John",
  "lastName": "Doe",
  "twoFactorEnabled": false
}
```

<Note>
  Save the `token` — you'll send it as a Bearer token on every protected request. The token carries your user identity, so no separate user id is needed. Standard tokens are valid for 24 hours (7 days when `remember` is `true`). See [Authentication](/authentication).
</Note>

Include the token in the `Authorization` header on all protected endpoints:

```bash theme={null}
Authorization: Bearer YOUR_JWT_TOKEN
```

## Step 2: Create an appointment

Create an appointment. The doctor is taken from your token.

```bash theme={null}
curl -X POST https://app.medisync.me/api/appointments/add \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Erstberatung",
    "date": "2026-07-15",
    "time": "14:30",
    "status": "planned",
    "language": "de",
    "appointment_type": "in_person"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "_id": "665f8a1b2c3d4e5f6789012f3",
    "name": "Erstberatung",
    "date": "2026-07-15T00:00:00.000Z",
    "time": "14:30",
    "status": "planned",
    "doctor_id": "6578a1b2c3d4e5f601234567",
    "language": "de",
    "appointment_type": "in_person"
  }
}
```

<Note>
  Keep the appointment `_id` — the recording, transcription, and notes endpoints are all scoped to it.
</Note>

## Step 3: Upload a recording

Upload the consultation audio for the appointment. This uses `multipart/form-data` with an `audio` file field.

```bash theme={null}
curl -X POST https://app.medisync.me/api/recordings/add/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "audio=@consultation_recording.wav"
```

<Tip>
  **Supported formats**: WAV (recommended), MP3, M4A. **Max file size**: 500 MB. 16 kHz / 16-bit mono gives the best transcription results. Only one recording is stored per appointment.
</Tip>

## Step 4: Get the transcription

Retrieve the transcription for the appointment. The response also reports the appointment's processing status, so you can poll until notes are ready.

```bash theme={null}
curl -X GET https://app.medisync.me/api/transcriptions/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "665f8a1b2c3d4e5f6789012f7",
      "appointment_id": "665f8a1b2c3d4e5f6789012f3",
      "transcription": [
        { "sender": "speaker_0", "message": "Guten Tag, was führt 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" }
      ]
    }
  ],
  "appointmentStatus": "processing",
  "appointmentUpdatedAt": "2026-07-15T13:31:00.000Z"
}
```

<Note>
  Each transcription is an ordered array of segments (`sender`, `message`, `start_time`). `sender` values such as `speaker_0` / `speaker_1` are diarization speaker labels. Adding a transcription automatically triggers clinical note generation in the background.
</Note>

## Step 5: Get the AI-generated notes

Once note generation finishes (`appointmentStatus` becomes `finished`), retrieve the clinical notes for the appointment:

```bash theme={null}
curl -X GET https://app.medisync.me/api/notes/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "665f1c2a9b1e8a0012ab34cd",
      "appointment_id": "665f8a1b2c3d4e5f6789012f3",
      "notes": "S: Patient reports chest pain since this morning...\nO: ...\nA: ...\nP: ...",
      "summary": "Chest pain, normal findings, continue monitoring"
    }
  ]
}
```

You can also set or overwrite the notes yourself:

```bash theme={null}
curl -X POST https://app.medisync.me/api/notes/add/665f8a1b2c3d4e5f6789012f3 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "S: ...\nO: ...\nA: ...\nP: ...",
    "summary": "Brief summary of the consultation"
  }'
```

## Real-time transcription (Speech API)

For live captioning during a consultation, stream audio to the **Speech API** over a WebSocket. The JWT is passed as a `token` query parameter (browser WebSocket clients cannot set custom headers).

```javascript theme={null}
const token = "YOUR_JWT_TOKEN";
const ws = new WebSocket(
  `wss://speech.medisync.me/api/v2/ws/transcribe?token=${token}`
);
ws.binaryType = "arraybuffer";

ws.onopen = () => ws.send(JSON.stringify({
  type: "config",
  audio: { encoding: "pcm_s16le", sample_rate: 16000, channels: 1 },
  language: "de",
  chunk: { strategy: "balanced" }
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "session_ready") startMic(ws);          // begin sending PCM frames
  else if (msg.type === "transcript") console.log(msg.text);
};
```

See the [Speech API](/websocket/introduction) for the full protocol.

## Error handling

MediSync APIs use standard HTTP status codes. Error bodies are JSON; the exact shape depends on the endpoint (some use `error`, some use `message`), and platform messages are returned in **German**.

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

<CardGroup cols={2}>
  <Card title="Common status codes" icon="triangle-exclamation">
    * `401` — missing or invalid token
    * `403` — not the owner of the resource, or subscription required
    * `404` — resource not found
    * `429` — rate limit exceeded (login only)
  </Card>

  <Card title="Authentication tips" icon="key">
    * Send `Authorization: Bearer <token>`
    * Re-authenticate when a token expires (there is no refresh endpoint)
    * Handle the 2FA challenge on login if enabled
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Live transcription" icon="microphone" href="/websocket/introduction">
    Real-time speech-to-text over a WebSocket.
  </Card>

  <Card title="Documents" icon="file-medical" href="/api-reference/documents/upload">
    Upload and manage clinical documents.
  </Card>

  <Card title="Connect API" icon="network-wired" href="/connect/introduction">
    Exchange data with hospital and practice systems.
  </Card>
</CardGroup>

## Support

Need help? Email [support@medisync.me](mailto:support@medisync.me) or visit [app.medisync.me](https://app.medisync.me).