Skip to content

Sessions and Recordings

Read and manage the authenticated user's Desktop Services session history, transcript results, and recordings.

Internal API

The Desktop API is internal and must not be used for customer integrations. Compatibility is not guaranteed, and these endpoints may change without notice.

Base path: /api/v1/desktop-services/sessions

Method Endpoint Description
GET /api/v1/desktop-services/sessions List Sessions
GET /api/v1/desktop-services/sessions/{sessionId} Get a Session
GET /api/v1/desktop-services/sessions/{sessionId}/results Get Transcript Results
PATCH /api/v1/desktop-services/sessions/{sessionId} Rename a Session
DELETE /api/v1/desktop-services/sessions/{sessionId} Permanently Delete a Session
GET /api/v1/desktop-services/sessions/{sessionId}/recording Download a Recording

Endpoints that address a specific session return 404 Not Found when it does not exist or is not owned by the authenticated user.

List Sessions

GET /api/v1/desktop-services/sessions

Requires Authentication - Scopes: desktop:app:use

Return a page of completed sessions that contain at least one recognized word, ordered by newest startTime first. The default view contains persisted history; set transientSession=true to request transient sessions instead.

Query Parameters
Parameter Type Required Default Description
page integer No 0 Zero-based page number. Minimum: 0.
size integer No 20 Page size. Range: 1–100.
nameContains string No - Return sessions whose name contains this text. Blank values do not filter.
caseInsensitive boolean No true Apply nameContains without case sensitivity.
transientSession boolean No false false returns persisted history; true returns transient sessions. 
curl "https://koldan.dixilang.com/api/v1/desktop-services/sessions?page=0&size=20&nameContains=visit" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    "https://koldan.dixilang.com/api/v1/desktop-services/sessions",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    params={"page": 0, "size": 20, "nameContains": "visit"},
)
response.raise_for_status()
print(response.json())
DesktopSessionListResponse
Field Type Nullable Description
items DesktopSession[] No Sessions in the current page. Default: empty array.
page integer No Current zero-based page number. Default: 0.
size integer No Page size used for this response. Default: 20.
total integer No Total matching sessions across all pages. Default when none match: 0.
DesktopSessionListResponse
{
  "items": [
    { "...": "..." }
  ],
  "page": 0,
  "size": 20,
  "total": 31
}
Status Description
200 OK Session page returned.
400 Bad Request Pagination or query value is invalid.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.

Get a Session

GET /api/v1/desktop-services/sessions/{sessionId}

Requires Authentication - Scopes: desktop:app:use

Return metadata for one owned session.

Path Parameters
Parameter Type Required Description
sessionId string (UUID) Yes Session identifier. 
curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
DesktopSession
Status Description
200 OK Session returned.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.
404 Not Found Session was not found for the current user.

Get Transcript Results

GET /api/v1/desktop-services/sessions/{sessionId}/results

Requires Authentication - Scopes: desktop:app:use

Return the finalized transcript segments in recognition order. Results are available only when the session state is FINISHED.

Path Parameters
Parameter Type Required Description
sessionId string (UUID) Yes Session identifier. 
curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/results \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

session_id = "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2"
response = requests.get(
    f"https://koldan.dixilang.com/api/v1/desktop-services/sessions/{session_id}/results",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
)
response.raise_for_status()
print(response.json())
DesktopSessionResultsResponse
Field Type Nullable Description
sessionId string (UUID) No Session identifier.
totalSegments integer No Number of entries in items. Default: 0.
items DesktopSessionSegment[] No Ordered finalized transcript segments. Default: empty array.
DesktopSessionResultsResponse
{
  "sessionId": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
  "totalSegments": 1,
  "items": [
    {
      "index": 0,
      "transcript": "Good morning.",
      "confidence": 0.97,
      "words": [
        { "...": "..." }
      ]
    }
  ]
}
Status Description
200 OK Transcript results returned.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.
404 Not Found Session was not found for the current user.
409 Conflict Session has not reached FINISHED.
500 Internal Server Error Transcript content could not be read.

Rename a Session

PATCH /api/v1/desktop-services/sessions/{sessionId}

Requires Authentication - Scopes: desktop:app:use

Rename a completed session. Leading and trailing whitespace is removed. An empty name is accepted and is returned as Untitled Session by subsequent reads.

Path Parameters
Parameter Type Required Description
sessionId string (UUID) Yes Session identifier.
DesktopSessionRenameRequest
Field Type Required Description
name string Yes New session name. Maximum: 255 characters.
DesktopSessionRenameRequest
{
  "name": "Follow-up visit"
}

curl -X PATCH https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Follow-up visit"}'
DesktopSession

Returns the updated session.

Status Description
200 OK Session renamed.
400 Bad Request Name is missing or exceeds 255 characters.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.
404 Not Found Session was not found for the current user.
409 Conflict Session has not reached FINISHED.

Permanently Delete a Session

DELETE /api/v1/desktop-services/sessions/{sessionId}

Requires Authentication - Scopes: desktop:app:use

Permanently delete the session record and its transcript, summaries, and recording. This action cannot be undone.

Path Parameters
Parameter Type Required Description
sessionId string (UUID) Yes Session identifier. 
curl -X DELETE https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response

This endpoint returns no body on success.

Status Description
204 No Content Session and associated content permanently deleted.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.
404 Not Found Session was not found for the current user.
409 Conflict The session or its post-processing is still active.
500 Internal Server Error Associated content could not be deleted. The operation can be retried.

Download a Recording

GET /api/v1/desktop-services/sessions/{sessionId}/recording

Requires Authentication - Scopes: desktop:app:use

Stream the session recording as mono, 16 kHz, 16-bit PCM. Download the entire object, one standard HTTP byte range, or a time range.

Path and Query Parameters
Parameter Type Required Default Description
sessionId string (UUID) Yes - Session identifier. (path)
startMilliseconds integer No 0 Inclusive start offset in milliseconds. Must be non-negative. (query)
endMilliseconds integer No End of recording Exclusive end offset in milliseconds. 0 or omission reads to the end. A value beyond the recording is clamped to its duration. (query)

Alternatively, send a single Range: bytes=<start>-<end> header. HTTP byte-range end offsets are inclusive. Suffix ranges such as bytes=-32000 are supported.

Choose one range form

Do not combine the Range header with startMilliseconds or endMilliseconds. The API returns 400 Bad Request when both forms are supplied.

curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/recording \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -o session.pcm

curl https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/recording \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Range: bytes=32000-63999" \
  -o session-part.pcm

curl "https://koldan.dixilang.com/api/v1/desktop-services/sessions/3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2/recording?startMilliseconds=1000&endMilliseconds=2000" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -o session-second.pcm
Binary Response
Header Example Description
Content-Type audio/x-raw;format=S16LE;rate=16000;channels=1 Raw signed 16-bit little-endian PCM audio.
Content-Length 32000 Bytes returned.
Accept-Ranges bytes Byte-range support.
Content-Range bytes 32000-63999/320000 Present on 206 Partial Content.
Content-Disposition inline; filename="{sessionId}.pcm" Suggested file name.
X-Audio-Sample-Rate 16000 Sample rate in hertz.
X-Audio-Channels 1 Channel count.
X-Audio-Sample-Format S16LE Signed 16-bit little-endian sample format.
X-Audio-Duration-Milliseconds 10000 Full recording duration, not just the selected range.
Status Description
200 OK Entire recording returned.
206 Partial Content Requested byte or time range returned.
400 Bad Request Range forms were combined, a time is negative or reversed, or a time value is too large.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Scope is missing or session history is unavailable.
404 Not Found Session or recording was not found for the current user.
416 Range Not Satisfiable The byte range is malformed or contains multiple ranges, or the requested byte/time range does not overlap the recording. Content-Range is bytes */{totalLength}.
500 Internal Server Error Recording metadata or content could not be read.

Data Models

DesktopSession

Field Type Nullable Description
id string (UUID) No Session identifier.
name string No Display name. Defaults to Untitled Session when no non-blank name is stored.
nameModifiedByUser boolean No Whether the user explicitly renamed the session. Default: false.
startTime string (ISO 8601) No Session start time.
endTime string (ISO 8601) Yes Terminal-state time; null while the session is not terminal.
durationMilliseconds integer No Recorded session duration in milliseconds. Default: 0.
wordsCount integer No Recognized word count. Default: 0.
speakersCount integer No Detected speaker count. Default: 0.
segmentCount integer No Final transcript segment count. Default: 0.
mode string enum No Session mode: DICTATION or CONVERSATION.
hasRecording boolean No Whether a downloadable recording is available. Default: false.
state string enum No Lifecycle state: CREATED, ACTIVE, FINISHED, CANCELLED, or FAILED. Initial value: CREATED.
failureReason string Yes Failure or cancellation detail, when available.
lastStateUpdate string (ISO 8601) No Most recent state transition or heartbeat time.
postDiarizationStatus string enum Yes Post-processing state: SKIPPED, SCHEDULED, PROCESSING, COMPLETED, or FAILED. null when not evaluated.
postDiarizationFailureReason string Yes Post-processing failure detail. Present only when postDiarizationStatus is FAILED.
postDiarizationCompletedAt string (ISO 8601) Yes Post-processing completion time. Present only when postDiarizationStatus is COMPLETED.
diarizationEnabled boolean No Whether speaker diarization was requested. Default: false.
transientSession boolean No Whether the session was created as transient. Default: false.
diarizationRequestedMaxSpeakersCount integer No Requested maximum speaker count. -1 means automatic detection without a configured maximum. Default: -1.
modelName string Yes Recognition model name, or null before a model is resolved.
DesktopSession
{
  "id": "3f13e99a-5f5c-4b50-bf02-f9fb45d74cd2",
  "name": "Follow-up visit",
  "nameModifiedByUser": true,
  "startTime": "2026-09-26T08:10:00Z",
  "endTime": "2026-09-26T08:12:14Z",
  "durationMilliseconds": 134000,
  "wordsCount": 327,
  "speakersCount": 2,
  "segmentCount": 18,
  "mode": "CONVERSATION",
  "hasRecording": true,
  "state": "FINISHED",
  "failureReason": null,
  "lastStateUpdate": "2026-09-26T08:12:14Z",
  "postDiarizationStatus": "COMPLETED",
  "postDiarizationFailureReason": null,
  "postDiarizationCompletedAt": "2026-09-26T08:13:02Z",
  "diarizationEnabled": true,
  "transientSession": false,
  "diarizationRequestedMaxSpeakersCount": 4,
  "modelName": "he-medical-v2"
}

DesktopSessionSegment

Field Type Nullable Description
index integer No Zero-based segment position.
transcript string No Final text for the segment.
confidence number No Segment confidence score.
words DesktopSessionWord[] No Word-level text, timing, confidence, and speaker assignment. Default: empty array.

DesktopSessionWord

Field Type Nullable Description
word string No Recognized word text.
punctuation string Yes Punctuation associated with the word.
startSeconds number No Start time relative to the beginning of the session.
endSeconds number No End time relative to the beginning of the session.
confidence number No Word confidence score.
speakerTag integer Yes One-based speaker tag when diarization is available.