Skip to main content
POST
/
voice
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.eka.care/voice/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'
{
  "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"
  }
}
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 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 are the best option; if you must use a raw API instead, use the deprecated EkaScribe v2 APIs.

​
upload_url depends on upload_type

The response’s upload_url is tailored to the chosen upload_type:
upload_typeupload_url schemeUse it with
chunkedhttps://…Upload Audio (HTTP binary)
streamwss://…Stream Audio (WebSocket)

​
Request fields

FieldTypeRequiredDescription
session_idstringNoClient-supplied session id (16–32 chars). If omitted, the server generates one.
session_modeenumNodictation (default) or consultation.
templatesstring[]NoUp to 2 template IDs to extract (e.g. eka_emr_template, clinical_notes_template).
modelenumNolite (default) or pro. From the discovery models list.
language_hintstring[]NoISO 639-1 code(s) hinting the spoken language(s), e.g. ["en"], ["hi"].
transcript_languagestringNoISO 639-1 code for the transcript output language.
upload_typeenumYeschunked, single, or stream.
communication_protocolenumYeshttp, websocket, or rpc.
additional_dataobjectNoArbitrary pass-through metadata returned in webhooks and status responses (≤4KB recommended).
patient_detailsobjectNoPatient demographic / identifier metadata. The oid key is promoted to patient_oid for indexing.

​
Response fields

FieldTypeDescription
session_idstringUnique session identifier — use in all subsequent calls.
statusstringAlways created on success.
created_atdatetimeISO 8601 creation timestamp.
expires_atdatetimeISO 8601 expiry timestamp. Sessions expire (~1 hour) if not ended.
upload_urlstringEndpoint to upload audio chunks to.
patient_detailsobjectEcho of the patient details supplied at creation, if any.

​
Choosing an upload type

upload_typeBehaviorNext step
chunkedSplit audio into short chunks and upload them in order over HTTP.Upload Audio — once per chunk (audio_0.webm, audio_1.webm, …)
streamStream audio in real time over a WebSocket.Stream Audio — connect to the returned wss:// URL

​
Next step

Send audio via Upload Audio (chunked) or Stream Audio (stream), then call End Session and poll Get Session for results.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
upload_type
enum<string>
required

Audio upload method. Must be advertised by discovery.

Available options:
chunked,
single,
stream
​
communication_protocol
enum<string>
required

Communication protocol used for the session.

Available options:
websocket,
http,
rpc
​
session_id
string

Optional client-supplied session id. If omitted, the server generates one.

Required string length: 16 - 32
Example:

"ses_abc123def456"

​
session_mode
enum<string>
default:dictation

Session mode.

Available options:
consultation,
dictation
​
templates
string[]

Template IDs to extract (max 2). See the templates endpoint for valid IDs.

Maximum array length: 2
Example:
["eka_emr_template"]
​
model
enum<string>
default:lite

Model ID from the discovery document.

Available options:
pro,
lite
​
language_hint
string[]

ISO 639-1 language code(s) hinting the audio input language.

Example:
["en"]
​
transcript_language
string

ISO 639-1 language code for the transcript output.

Example:

"en"

​
additional_data
object

Pass-through metadata returned in webhooks and status responses (≤4KB recommended).

​
patient_details
object

Patient demographic / identifier metadata. oid is promoted to patient_oid for indexing.

Response

Session created

​
session_id
string

Unique session identifier. Use in all subsequent calls.

​
status
string
Example:

"created"

​
created_at
string<date-time>
​
expires_at
string<date-time>
​
upload_url
string

Endpoint for uploading audio to this session.

​
patient_details
object