> ## 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.
# Create Session
> Create a new scribing session. Returns a `session_id` that must be used in every subsequent call (audio upload, end session, status polling) and an `upload_url` to which audio is sent. `upload_type` and `communication_protocol` are required and must be one of the methods advertised by the discovery endpoint.
Create a new scribing session. The response returns a `session_id` that ties together every subsequent call — audio upload, end session and status polling — and an `upload_url` that audio chunks are POSTed to.
`upload_type` and `communication_protocol` are **required**. Both must be values advertised by the [Discovery](/api-reference/health-ai/ekascribe/protocol/discovery) endpoint (`capabilities.upload_methods` and the supported protocols).
**Supported upload types via the protocol APIs:** only **`chunked`** (HTTP binary upload) and **`stream`** (WebSocket) are currently supported through these APIs. For other use cases (e.g. single full-file / batch upload), the **[SDKs](/api-reference/health-ai/ekascribe/quick-start)** are the best option; if you must use a raw API instead, use the [deprecated EkaScribe v2 APIs](/api-reference/health-ai/ekascribe/ekascribe-v2/overview).
### `upload_url` depends on `upload_type`
The response's `upload_url` is tailored to the chosen `upload_type`:
| `upload_type` | `upload_url` scheme | Use it with |
| ------------- | ------------------- | -------------------------------------------------------------------------------------- |
| `chunked` | `https://…` | [Upload Audio](/api-reference/health-ai/ekascribe/protocol/upload-audio) (HTTP binary) |
| `stream` | `wss://…` | [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio) (WebSocket) |
## Request fields
| Field | Type | Required | Description |
| ------------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | string | No | Client-supplied session id (16–32 chars). If omitted, the server generates one. |
| `session_mode` | enum | No | `dictation` (default) or `consultation`. |
| `templates` | string\[] | No | Up to **2** template IDs to extract (e.g. `eka_emr_template`, `clinical_notes_template`). |
| `model` | enum | No | `lite` (default) or `pro`. From the discovery `models` list. |
| `language_hint` | string\[] | No | ISO 639-1 code(s) hinting the spoken language(s), e.g. `["en"]`, `["hi"]`. If you're not offering users a language change option in your UI, use `["auto_detect"]` for the best results. |
| `transcript_language` | string | No | ISO 639-1 code for the transcript output language. |
| `upload_type` | enum | **Yes** | `chunked`, `single`, or `stream`. |
| `communication_protocol` | enum | **Yes** | `http`, `websocket`, or `rpc`. |
| `additional_data` | object | No | Arbitrary pass-through metadata returned in webhooks and status responses (≤4KB recommended). |
| `patient_details` | object | No | Patient demographic / identifier metadata. The `oid` key is promoted to `patient_oid` for indexing. |
## Response fields
| Field | Type | Description |
| ----------------- | -------- | ------------------------------------------------------------------- |
| `session_id` | string | Unique session identifier — use in all subsequent calls. |
| `status` | string | Always `created` on success. |
| `created_at` | datetime | ISO 8601 creation timestamp. |
| `expires_at` | datetime | ISO 8601 expiry timestamp. Sessions expire (\~1 hour) if not ended. |
| `upload_url` | string | Endpoint to upload audio chunks to. |
| `patient_details` | object | Echo of the patient details supplied at creation, if any. |
## Choosing an upload type
| `upload_type` | Behavior | Next step |
| ------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `chunked` | Split audio into short chunks and upload them in order over HTTP. | [Upload Audio](/api-reference/health-ai/ekascribe/protocol/upload-audio) — once per chunk (`audio_0.webm`, `audio_1.webm`, …) |
| `stream` | Stream audio in real time over a WebSocket. | [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio) — connect to the returned `wss://` URL |
## Next step
Send audio via [Upload Audio](/api-reference/health-ai/ekascribe/protocol/upload-audio) (chunked) or [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio) (stream), then call [End Session](/api-reference/health-ai/ekascribe/protocol/end-session) and poll [Get Session](/api-reference/health-ai/ekascribe/protocol/get-session) for results.
## OpenAPI
````yaml POST /voice/v1/sessions
openapi: 3.0.1
info:
title: EkaScribe Protocol API (MedScribeAlliance v0.1)
version: '0.1'
description: >
Session-based medical voice capture API implementing the MedScribeAlliance
Protocol v0.1. Discover service capabilities, create a session, stream audio
chunks, then end the session to trigger asynchronous transcription and
structured-template extraction.
servers:
- url: https://api.eka.care
description: Production server
- url: https://api.dev.eka.care
description: Development server
security: []
paths:
/voice/v1/sessions:
post:
tags:
- protocol
summary: Create Session
description: >
Create a new scribing session. Returns a `session_id` that must be used
in every subsequent call (audio upload, end session, status polling) and
an `upload_url` to which audio is sent. `upload_type` and
`communication_protocol` are required and must be one of the methods
advertised by the discovery endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
example:
session_mode: dictation
templates:
- eka_emr_template
model: pro
language_hint:
- en
transcript_language: en
upload_type: chunked
communication_protocol: http
additional_data:
source: mobile_app
app_version: 1.0.0
patient_details:
oid: PAT-12345
name: John Doe
responses:
'201':
description: Session created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionResponse'
example:
session_id: ses_abc123def456
status: created
created_at: '2025-01-19T10:30:00Z'
expires_at: '2025-01-19T11:30:00Z'
upload_url: https://api.eka.care/voice/v1/sessions/ses_abc123def456/audio
patient_details:
oid: PAT-12345
name: John Doe
'400':
description: Invalid request (e.g. template validation failed)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- auth: []
components:
schemas:
CreateSessionRequest:
type: object
required:
- upload_type
- communication_protocol
properties:
session_id:
type: string
minLength: 16
maxLength: 32
description: >-
Optional client-supplied session id. If omitted, the server
generates one.
example: ses_abc123def456
session_mode:
type: string
enum:
- consultation
- dictation
default: dictation
description: Session mode.
templates:
type: array
maxItems: 2
items:
type: string
description: >-
Template IDs to extract (max 2). See the templates endpoint for
valid IDs.
example:
- eka_emr_template
model:
type: string
enum:
- pro
- lite
default: lite
description: Model ID from the discovery document.
language_hint:
type: array
items:
type: string
description: ISO 639-1 language code(s) hinting the audio input language.
example:
- en
transcript_language:
type: string
description: ISO 639-1 language code for the transcript output.
example: en
upload_type:
type: string
enum:
- chunked
- single
- stream
description: Audio upload method. Must be advertised by discovery.
communication_protocol:
type: string
enum:
- websocket
- http
- rpc
description: Communication protocol used for the session.
additional_data:
type: object
additionalProperties: true
description: >-
Pass-through metadata returned in webhooks and status responses
(≤4KB recommended).
patient_details:
type: object
additionalProperties: true
description: >-
Patient demographic / identifier metadata. `oid` is promoted to
`patient_oid` for indexing.
CreateSessionResponse:
type: object
properties:
session_id:
type: string
description: Unique session identifier. Use in all subsequent calls.
status:
type: string
example: created
created_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
upload_url:
type: string
description: Endpoint for uploading audio to this session.
patient_details:
type: object
additionalProperties: true
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Machine-readable error code.
example: invalid_audio_format
message:
type: string
description: Human-readable error message.
example: Audio format 'audio/mp3' is not supported
details:
type: object
additionalProperties: true
description: Additional error context.
securitySchemes:
auth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your auth token.
````