Desktop - Profiles and Preferences

Manage user profiles and preferences for the Koldan Desktop application. These profiles are specific to the desktop client and are separate from the general user accounts managed through the Administration Users API.

Koldan Desktop Only

The profiles and preferences described on this page apply exclusively to the Koldan Desktop application. They control desktop-specific settings such as microphone configuration, keyboard shortcuts, output behaviour, and word mappings.

Base path: /api/v1/profiles

Profile Management

Method	Endpoint	Description
`GET`	`/api/v1/profiles`	List All Profiles
`POST`	`/api/v1/profiles/search`	Search Profiles
`GET`	`/api/v1/profiles/{userUuid}`	Get Profile
`PUT`	`/api/v1/profiles/{userUuid}`	Update Profile

Preferences Management (Admin)

Method	Endpoint	Description
`GET`	`/api/v1/profiles/user-preferences`	List All Preferences
`GET`	`/api/v1/profiles/user-preferences/{userUuid}`	Get User Preferences
`PUT`	`/api/v1/profiles/user-preferences/{userUuid}`	Update User Preferences
`POST`	`/api/v1/profiles/user-preferences/reset-to-default/{userUuid}`	Reset Preferences to Default

List All Profiles

`GET` /api/v1/profiles

Requires Authentication - Scopes: desktop:profiles:read

Returns all desktop user profiles for the current tenant.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/profiles \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/profiles",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

`UserProfileDTO[]`

Status	Description
`200 OK`	List of desktop user profiles returned.
`204 No Content`	No profiles found.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.

Search Profiles

`POST` /api/v1/profiles/search

Requires Authentication - Scopes: desktop:profiles:read

Search desktop user profiles with optional filtering and pagination. When a session time filter is provided, only profiles with activity matching the criteria are returned. Setting size to 0 returns only the total count without profile data.

`UserProfilesRequest`

Field	Type	Required	Description
`filter`	`UserProfilesFilter`	No	Optional filter criteria.
`page`	`integer`	No	Page number, starting from `0`. Default: `0`.
`size`	`integer`	No	Page size. Set to `0` to return only the total count. Default: `50`.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/profiles/search \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "sessionsFilter": {
        "startTimeAfter": "2025-03-01T00:00:00Z",
        "startTimeBefore": "2025-03-31T23:59:59Z"
      }
    },
    "page": 0,
    "size": 50
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/profiles/search",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "filter": {
            "sessionsFilter": {
                "startTimeAfter": "2025-03-01T00:00:00Z",
                "startTimeBefore": "2025-03-31T23:59:59Z"
            }
        },
        "page": 0,
        "size": 50
    }
)
print(resp.json())

`UserProfilesPage`

Status	Description
`200 OK`	Paginated search results returned.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.

Get Profile

`GET` /api/v1/profiles/{userUuid}

Requires Authentication - Scopes: desktop:profiles:read

Retrieve a specific desktop user profile by user UUID.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/profiles/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/profiles/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

`UserProfileDTO`

Status	Description
`200 OK`	Profile returned.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.
`404 Not Found`	Profile not found for the specified UUID.

Update Profile

`PUT` /api/v1/profiles/{userUuid}

Requires Authentication - Scopes: desktop:profiles:write

Update a desktop user profile. Allows modifying the profile note and assigned preset names.

`UserProfileUpdateDTO`

Field	Type	Required	Description
`note`	`string`	No	Free-text note associated with the profile.
`presetsNames`	`string[]`	No	Set of preset names assigned to this user.

cURLPython

curl -X PUT https://koldan.dixilang.com/api/v1/profiles/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Cardiology department user",
    "presetsNames": ["medical-he", "general-he"]
  }'

import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/profiles/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "note": "Cardiology department user",
        "presetsNames": ["medical-he", "general-he"]
    }
)
print(resp.json())

`UserProfileDTO`

Status	Description
`200 OK`	Profile updated. Returns the updated profile.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.
`404 Not Found`	Profile not found for the specified UUID.

List All Preferences

`GET` /api/v1/profiles/user-preferences

Requires Authentication - Scopes: desktop:profiles:read

Returns all desktop user preferences configurations for the current tenant.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/profiles/user-preferences \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/profiles/user-preferences",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

`UserPreferencesDto[]`

Status	Description
`200 OK`	List of user preferences returned.
`204 No Content`	No preferences found.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.

Get User Preferences

`GET` /api/v1/profiles/user-preferences/{userUuid}

Requires Authentication - Scopes: desktop:profiles:read

Retrieve desktop preferences for a specific user.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/profiles/user-preferences/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/profiles/user-preferences/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

`UserPreferencesDto`

Status	Description
`200 OK`	User preferences returned.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.
`404 Not Found`	Preferences not found for the specified user.

Update User Preferences

`PUT` /api/v1/profiles/user-preferences/{userUuid}

Requires Authentication - Scopes: desktop:profiles:write

Update desktop preferences for a specific user. Provide the full PreferencesDTO object with the desired settings.

`PreferencesDTO`

cURLPython

curl -X PUT https://koldan.dixilang.com/api/v1/profiles/user-preferences/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "microphoneSettings": {
      "enableLoopbackRecording": false,
      "preferredDeviceName": "Microphone (Realtek Audio)",
      "alwaysUseDefaultDevice": true,
      "startSessionToggle": "TOGGLE_ENABLED"
    },
    "outputPreferences": {
      "method": "OM_FOLLOW_MOUSE_CURSOR",
      "pasteStrategy": "PS_CTRL_V",
      "pasteCase": "PC_ON_FINAL_RESULT",
      "simulateTrailingSpaceOrNewline": true
    },
    "lastPresetName": "medical-he"
  }'

import requests

resp = requests.put(
    "https://koldan.dixilang.com/api/v1/profiles/user-preferences/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "microphoneSettings": {
            "enableLoopbackRecording": False,
            "preferredDeviceName": "Microphone (Realtek Audio)",
            "alwaysUseDefaultDevice": True,
            "startSessionToggle": "TOGGLE_ENABLED"
        },
        "outputPreferences": {
            "method": "OM_FOLLOW_MOUSE_CURSOR",
            "pasteStrategy": "PS_CTRL_V",
            "pasteCase": "PC_ON_FINAL_RESULT",
            "simulateTrailingSpaceOrNewline": True
        },
        "lastPresetName": "medical-he"
    }
)
print(resp.json())

`UserPreferencesDto`

Status	Description
`200 OK`	Preferences updated. Returns the updated preferences.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.

Reset Preferences to Default

`POST` /api/v1/profiles/user-preferences/reset-to-default/{userUuid}

Requires Authentication - Scopes: desktop:profiles:write

Reset a user's desktop preferences to the system default configuration. This removes any custom settings the user has configured.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/profiles/user-preferences/reset-to-default/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/profiles/user-preferences/reset-to-default/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)

Status	Description
`200 OK`	Preferences reset to default.
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	Insufficient scope.
`404 Not Found`	Preferences not found for the specified user.

Data Models

UserProfileDTO

Desktop user profile containing identity information, activity timestamps, and assigned presets.

Field	Type	Description
`userUuid`	`string` (UUID)	Unique identifier for the user.
`username`	`string`	Login username.
`displayName`	`string`	User's display name.
`email`	`string`	User's email address.
`note`	`string`	Administrator-defined note for the profile.
`metadata`	`string`	Additional metadata associated with the profile.
`isEnabled`	`boolean`	Whether the profile is enabled.
`createdAt`	`string` (ISO 8601)	Timestamp when the profile was created.
`updatedAt`	`string` (ISO 8601)	Timestamp when the profile was last updated.
`lastLoginAt`	`string` (ISO 8601)	Timestamp of the user's last login.
`presetsNames`	`string[]`	Set of preset names assigned to this user.
`lastSpeechRecognitionSessionTime`	`string` (ISO 8601)	Timestamp of the user's last speech recognition session.
`tenantId`	`string` (UUID)	Tenant to which the profile belongs.

UserProfileUpdateDTO

Request body for updating a desktop user profile.

Field	Type	Description
`note`	`string`	Free-text note associated with the profile.
`presetsNames`	`string[]`	Set of preset names to assign to the user.

UserPreferencesDto

Wrapper object that associates a preferences configuration with a specific user.

Field	Type	Description
`id`	`integer`	Unique identifier for the preferences record.
`userUuid`	`string` (UUID)	UUID of the user these preferences belong to.
`preferences`	`PreferencesDTO`	The full desktop preferences configuration.

PreferencesDTO

Complete desktop application preferences configuration. All sections are optional — omitted sections retain their current values.

Field	Type	Description
`microphoneSettings`	`MicrophonePreferencesDTO`	Microphone and audio input configuration.
`outputPreferences`	`OutputPreferencesDTO`	Text output and paste behaviour configuration.
`keyboardMapping`	`KeyboardMappingDTO`	Keyboard shortcut mappings.
`wordMapping`	`UserWordMappingDTO[]`	Custom word replacement rules.
`lastPresetName`	`string`	Name of the last used preset.
`soundPreferences`	`SoundPreferencesDTO`	Sound notification settings.

MicrophonePreferencesDTO

Microphone and audio input settings for the desktop client.

Field	Type	Description
`enableLoopbackRecording`	`boolean`	Whether to enable loopback (system audio) recording.
`preferredDeviceName`	`string`	Name of the preferred audio input device.
`alwaysUseDefaultDevice`	`boolean`	Whether to always use the system default audio device.
`startSessionToggle`	`StartSessionToggle`	Toggle behaviour for starting a session.
`philipsIntegrationPreferences`	`PhilipsIntegrationPreferencesDTO`	Philips dictation device integration settings.

OutputPreferencesDTO

Configuration for how transcribed text is delivered to the target application.

Field	Type	Description
`method`	`OutputMethod`	How the target window is selected for text output.
`windowTitleNameExact`	`string`	Exact window title to match (used with `OM_WINDOW_TITLE_NAME_EXACT`).
`windowTitleNameContains`	`string`	Substring to match in window title (used with `OM_WINDOW_TITLE_NAME_CONTAINS`).
`pasteStrategy`	`PasteStrategy`	Keyboard shortcut or method used to paste text.
`pasteCase`	`PasteCase`	When to paste transcription results.
`simulateTrailingSpaceOrNewline`	`boolean`	Whether to append a trailing space or newline after pasting.

KeyboardMappingDTO

Keyboard shortcut assignments for desktop client actions.

Field	Type	Description
`startSessionCombo`	`KeyboardCombinationDTO`	Shortcut to start a recognition session.
`stopSessionCombo`	`KeyboardCombinationDTO`	Shortcut to stop a recognition session.
`pasteLastResultCombo`	`KeyboardCombinationDTO`	Shortcut to paste the last transcription result.

KeyboardCombinationDTO

Represents a keyboard shortcut as a combination of modifier keys and a primary key.

Field	Type	Description
`modifiers`	`ModifierKey[]`	List of modifier keys (e.g. Ctrl, Shift, Alt).
`key`	`Key`	The primary key in the combination.

UserWordMappingDTO

A custom word replacement rule. When the speech engine produces the key word, it is automatically replaced with value in the output.

Field	Type	Description
`key`	`string`	The spoken word or phrase to match.
`value`	`string`	The replacement text to output.

PhilipsIntegrationPreferencesDTO

Settings for integration with Philips dictation devices.

Field	Type	Description
`enabled`	`boolean`	Whether Philips device integration is enabled.
`startButtonId`	`integer`	The Philips device button ID used to start recording.

SoundPreferencesDTO

Sound notification settings.

Field	Type	Description
`enableNotificationSoundOnStartAndStop`	`boolean`	Whether to play a notification sound when a session starts or stops.

UserProfilesPage

Paginated response for profile search results.

Field	Type	Description
`size`	`integer`	Page size used in the request.
`total`	`integer`	Total number of profiles matching the filter.
`page`	`integer`	Current page number.
`profiles`	`ProfileDTO[]`	List of profiles on the current page.

ProfileDTO

Summary profile returned in search results.

Field	Type	Description
`userUuid`	`string` (UUID)	Unique identifier for the user.
`username`	`string`	Login username.
`displayName`	`string`	User's display name.
`lastSpeechRecognitionSessionTime`	`string` (ISO 8601)	Timestamp of the user's last speech recognition session.
`activeInPeriod`	`boolean`	Whether the user was active within the filtered time period.

UserProfilesRequest

Request body for the profile search endpoint.

Field	Type	Description
`filter`	`UserProfilesFilter`	Optional filter criteria.
`page`	`integer`	Page number, starting from `0`. Default: `0`.
`size`	`integer`	Page size. Set to `0` to return only the total count. Default: `50`.

UserProfilesFilter

Filter criteria for profile search.

Field	Type	Description
`sessionsFilter`	`SessionsFilter`	Filter profiles based on their associated session activity.

SessionsFilter

Time-based filter for sessions. All timestamps are in UTC (ISO 8601 format).

Field	Type	Description
`startTimeAfter`	`string` (ISO 8601)	Include sessions starting at or after this timestamp (inclusive).
`startTimeBefore`	`string` (ISO 8601)	Include sessions starting before this timestamp (exclusive).
`endTimeAfter`	`string` (ISO 8601)	Include sessions ending at or after this timestamp (inclusive).
`endTimeBefore`	`string` (ISO 8601)	Include sessions ending before this timestamp (exclusive).

Enumerations

StartSessionToggle

Controls whether the session start key acts as a toggle.

Value	Description
`TOGGLE_DISABLED`	Start and stop require separate key presses.
`TOGGLE_ENABLED`	The same key press toggles the session on and off.

OutputMethod

Determines how the target window for text output is selected.

Value	Description
`OM_FOLLOW_MOUSE_CURSOR`	Output text to the window under the mouse cursor.
`OM_WINDOW_TITLE_NAME_EXACT`	Output text to a window whose title matches exactly.
`OM_WINDOW_TITLE_NAME_CONTAINS`	Output text to a window whose title contains the specified substring.

PasteStrategy

The keyboard method used to paste transcribed text into the target window.

Value	Description
`PS_SHIFT_INSERT`	Paste using Shift+Insert.
`PS_CTRL_V`	Paste using Ctrl+V.
`PS_TYPE_SIMULATE`	Simulate typing the text character by character.

PasteCase

Determines when transcription results are pasted.

Value	Description
`PC_ON_FINAL_RESULT`	Paste only when the final transcription result is available.
`PC_ON_SEGMENT_RESULT`	Paste as each segment result becomes available.

Key

Available primary keys for keyboard shortcuts.

Value	Description
`KEY_F1` – `KEY_F12`	Function keys F1 through F12.
`KEY_DELETE`	Delete key.
`KEY_REMOVE`	Remove key.
`KEY_TAB`	Tab key.
`KEY_ESC`	Escape key.
`KEY_SPACE`	Space bar.
`KEY_ARROW_LEFT`, `KEY_ARROW_RIGHT`, `KEY_ARROW_UP`, `KEY_ARROW_DOWN`	Arrow keys.
`KEY_INSERT`	Insert key.
`KEY_HOME`, `KEY_END`	Home and End keys.
`KEY_PAGE_UP`, `KEY_PAGE_DOWN`	Page Up and Page Down keys.
`KEY_SUPER`	Super (Windows) key.
`KEY_ENTER`	Enter key.
`KEY_LETTER_A` – `KEY_LETTER_Z`	Letter keys A through Z.
`KEY_NUMBER_0` – `KEY_NUMBER_9`	Number keys 0 through 9.
`KEY_TILDE`	Tilde (~) key.

ModifierKey

Modifier keys used in keyboard shortcuts.

Value	Description
`MKEY_CTRL`	Control key.
`MKEY_SHIFT`	Shift key.
`MKEY_ALT`	Alt key.

Desktop - Profiles and Preferences

Profile Management

Preferences Management (Admin)

List All Profiles

GET /api/v1/profiles

Search Profiles

POST /api/v1/profiles/search

Get Profile

GET /api/v1/profiles/{userUuid}

Update Profile

PUT /api/v1/profiles/{userUuid}

List All Preferences

GET /api/v1/profiles/user-preferences

Get User Preferences

GET /api/v1/profiles/user-preferences/{userUuid}

Update User Preferences

PUT /api/v1/profiles/user-preferences/{userUuid}

Reset Preferences to Default

POST /api/v1/profiles/user-preferences/reset-to-default/{userUuid}

Data Models

UserProfileDTO

UserProfileUpdateDTO

UserPreferencesDto

PreferencesDTO

MicrophonePreferencesDTO

OutputPreferencesDTO

KeyboardMappingDTO

KeyboardCombinationDTO

UserWordMappingDTO

PhilipsIntegrationPreferencesDTO

SoundPreferencesDTO

UserProfilesPage

ProfileDTO

UserProfilesRequest

UserProfilesFilter

SessionsFilter

Enumerations

StartSessionToggle

OutputMethod

PasteStrategy

PasteCase

Key

ModifierKey

`GET` /api/v1/profiles

`POST` /api/v1/profiles/search

`GET` /api/v1/profiles/{userUuid}

`PUT` /api/v1/profiles/{userUuid}

`GET` /api/v1/profiles/user-preferences

`GET` /api/v1/profiles/user-preferences/{userUuid}

`PUT` /api/v1/profiles/user-preferences/{userUuid}

`POST` /api/v1/profiles/user-preferences/reset-to-default/{userUuid}