> ## 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. Only `upload_type` is required — use `single` (one audio file, max 10 MB via the API; for larger recordings use the SDKs, which chunk automatically) unless you need chunked or streaming upload. The communication protocol is derived from `upload_type` by the server: `single`/`chunked` → http, `stream` → websocket.
Create a scribing session. Only `upload_type` is required — use `single` for the simplest flow (one audio file). Save the returned `session_id` for all subsequent calls.
`single` uploads are capped at **10 MB** — for larger recordings use `chunked` or an [SDK](/ekascribe/quickstart#prefer-an-sdk). The communication protocol is derived automatically: `single`/`chunked` → http, `stream` → websocket (returns a `wss://` `upload_url`).
**Next:** [Upload Audio](/ekascribe/api-reference/sessions/upload-audio) → [End Session](/ekascribe/api-reference/sessions/end-session) → [Get Session](/ekascribe/api-reference/sessions/get-session).
## 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. Only `upload_type` is required —
use `single` (one audio file, max 10 MB via the API; for larger
recordings use the SDKs, which chunk automatically) unless you need
chunked or streaming upload. The communication protocol is derived from
`upload_type` by the server: `single`/`chunked` → http, `stream` →
websocket.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
example:
language_hint:
- en
model: pro
templates:
- clinical_notes_template
upload_type: single
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
properties:
language_hint:
type: array
items:
type: string
description: >
ISO 639-1 language code(s) hinting the audio input language. If your
UI doesn't offer a language picker, use `["auto_detect"]` for the
best results.
example:
- en
model:
type: string
enum:
- pro
- lite
default: pro
description: Model ID from the discovery document.
templates:
type: array
maxItems: 2
items:
type: string
description: >-
Optional template IDs to extract (max 2). See List Templates for
valid IDs.
example:
- clinical_notes_template
upload_type:
type: string
enum:
- single
- chunked
- stream
default: single
description: >
Audio upload method. `single` — one complete audio file up to 10 MB;
`chunked` — sequential HTTP chunks for longer recordings; `stream` —
real-time WebSocket. The communication protocol is derived
automatically (single/chunked → http, stream → websocket).
session_id:
type: string
minLength: 16
maxLength: 32
description: >-
Optional client-supplied session id (16–32 chars). If omitted, the
server generates one.
example: ses_abc123def456
additional_data:
type: object
additionalProperties: true
description: >-
Optional pass-through metadata returned in webhooks and status
responses (≤4KB recommended).
patient_details:
type: object
additionalProperties: true
description: >-
Optional 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.
````