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

# Overview

> Session-based EkaScribe protocol APIs (MedScribeAlliance v0.1)

The **EkaScribe Protocol APIs** implement the [MedScribeAlliance Protocol v0.1](https://medscribealliance.org) — a standardized, session-based interface for medical voice capture and structured transcription. They replace the older transaction-based EkaScribe v2 APIs (presigned URL → upload → init → result), which are now **deprecated**.

<Info>
  All protocol endpoints are served under the base path `/voice/v1` on `https://api.eka.care` (production) or `https://api.dev.eka.care` (development).
</Info>

## Why the protocol APIs

* **Single session lifecycle** — one `session_id` ties discovery, upload, processing and results together; no separate transaction/presigned-URL juggling.
* **Direct chunked upload** — stream audio chunks straight to the session as raw binary, or send one file and let the server chunk it via VAD.
* **Self-describing** — the discovery endpoint advertises supported models, audio formats, languages and limits so clients can configure themselves at runtime.
* **Provider-agnostic** — the same protocol backs HTTP, WebSocket and streaming clients.

## Authentication

Every endpoint except [Discovery](/api-reference/health-ai/ekascribe/protocol/discovery) requires a bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

**Don't have an API key?** Contact the Eka Care team to get started.

## The session flow

```
1. Discovery        GET  /voice/v1/.well-known/medscribealliance   (public)
        │           → capabilities, models, languages
        ▼
2. Create Session   POST /voice/v1/sessions                        → 201 Created
        │           → session_id, upload_url, expires_at
        ▼
3. Send audio  ── one of, based on upload_type ──────────────────────────
        │     chunked → Upload Audio (HTTP binary, repeat per chunk)  → 200 OK
        │              POST /voice/v1/sessions/{session_id}/audio/{file_name}
        │     stream  → Stream Audio (WebSocket)
        │              wss://…/voice/v1/stream/sessions/{stream_id}/audio
        ▼
4. End Session      POST /voice/v1/sessions/{session_id}/end       → 202 Accepted
        │           → processing started (canonical finalize for both paths)
        ▼
5. Get Session      GET  /voice/v1/sessions/{session_id}          (poll ~1s until ≠202)
                    → 200 completed · 206 partial · 410 expired
```

<Steps>
  <Step title="Discover capabilities">
    Call [Discovery](/api-reference/health-ai/ekascribe/protocol/discovery) to learn which `models`, `audio_formats` and `upload_methods` are available. Cache the result (valid for 3 hours).
  </Step>

  <Step title="Create a session">
    Call [Create Session](/api-reference/health-ai/ekascribe/protocol/create-session) with your chosen `model`, `templates`, `upload_type` and `communication_protocol`. Store the returned `session_id` and `upload_url`.
  </Step>

  <Step title="Send audio">
    Based on your `upload_type`: stream chunks over HTTP with [Upload Audio](/api-reference/health-ai/ekascribe/protocol/upload-audio) (`chunked`), or stream in real time over a WebSocket with [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio) (`stream`).
  </Step>

  <Step title="End the session">
    Call [End Session](/api-reference/health-ai/ekascribe/protocol/end-session) to lock the session and trigger transcription + template extraction. This is the canonical finalize for both audio paths.
  </Step>

  <Step title="Retrieve results">
    Poll [Get Session](/api-reference/health-ai/ekascribe/protocol/get-session) at \~1-second intervals (or register a webhook) until the status is no longer `202`. The response carries the transcript and structured template results.
  </Step>
</Steps>

## Key identifiers

| ID           | Created by                                       | Used in                                   |
| ------------ | ------------------------------------------------ | ----------------------------------------- |
| `session_id` | Create Session (or client-supplied, 16–32 chars) | Upload Audio, End Session, status polling |
| `upload_url` | Create Session                                   | The endpoint audio chunks are POSTed to   |

## API reference

| API                                                                          | Endpoint                                                 | Auth   |
| ---------------------------------------------------------------------------- | -------------------------------------------------------- | ------ |
| [Discovery](/api-reference/health-ai/ekascribe/protocol/discovery)           | `GET /voice/v1/.well-known/medscribealliance`            | Public |
| [Create Session](/api-reference/health-ai/ekascribe/protocol/create-session) | `POST /voice/v1/sessions`                                | Bearer |
| [Upload Audio](/api-reference/health-ai/ekascribe/protocol/upload-audio)     | `POST /voice/v1/sessions/{session_id}/audio/{file_name}` | Bearer |
| [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio)     | `wss://…/voice/v1/stream/sessions/{stream_id}/audio`     | Bearer |
| [End Session](/api-reference/health-ai/ekascribe/protocol/end-session)       | `POST /voice/v1/sessions/{session_id}/end`               | Bearer |
| [Get Session](/api-reference/health-ai/ekascribe/protocol/get-session)       | `GET /voice/v1/sessions/{session_id}`                    | Bearer |