Skip to content

Identity and Preferences

Read the signed-in user's Desktop identity and manage that user's Desktop application preferences. Preferences include audio input, output routing, shortcuts, word mappings, sound, the last selected preset and mode, and conversation settings.

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.

Method Endpoint Description
GET /api/v1/desktop-services/self Get Current User
GET /api/v1/desktop/self/preferences Get Preferences
PUT /api/v1/desktop/self/preferences Update Preferences

Get Current User

GET /api/v1/desktop-services/self

Requires Authentication - Scopes: desktop:app:use

Return the Desktop profile associated with the access token.

curl https://koldan.dixilang.com/api/v1/desktop-services/self \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    "https://koldan.dixilang.com/api/v1/desktop-services/self",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
)
response.raise_for_status()
print(response.json())
DesktopCurrentUserResponse
Field Type Nullable Description
userId string (UUID) No Stable user identifier.
username string No Login name.
displayName string No User-facing name.
email string Yes Email address, or null when none is available.
DesktopCurrentUserResponse
{
  "userId": "d198edd6-c55b-4b72-af22-02fd173e2fb0",
  "username": "alex",
  "displayName": "Alex Smith",
  "email": "alex@example.com"
}
Status Description
200 OK Identity returned.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Token does not include desktop:app:use.
404 Not Found No Desktop profile exists for the authenticated user.

Get Preferences

GET /api/v1/desktop/self/preferences

Requires Authentication - Scopes: desktop:app:use

Return the authenticated user's preferences. A default preferences record is created when the user does not have one yet.

curl https://koldan.dixilang.com/api/v1/desktop/self/preferences \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    "https://koldan.dixilang.com/api/v1/desktop/self/preferences",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
)
response.raise_for_status()
print(response.json())
DesktopPreferencesResponse
Status Description
200 OK Preferences returned.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Token does not include desktop:app:use.
404 Not Found No Desktop profile exists for the authenticated user.

Update Preferences

PUT /api/v1/desktop/self/preferences

Requires Authentication - Scopes: desktop:app:use

Replace the supplied top-level preference sections and preserve omitted sections. A top-level JSON null is treated as omitted. To clear all word mappings, send "wordMapping": []. To leave mappings unchanged, omit wordMapping.

Section replacement

Each supplied object, such as microphoneSettings or outputPreferences, replaces that complete section. Read the current preferences first, modify the fields you need, and send the complete section back.

Inside a supplied section, include every member marked required below. Omitted optional boolean and integer members use false and 0 respectively.

DesktopPreferences
DesktopPreferences
{
  "wordMapping": [
    {
      "key": "next line",
      "value": "\n"
    }
  ],
  "lastPresetName": "general-he",
  "lastSpeechSessionMode": "SMODE_DICTATION",
  "conversationPreferences": {
    "maxConversationSpeakers": 4
  }
}

curl -X PUT https://koldan.dixilang.com/api/v1/desktop/self/preferences \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wordMapping": [
      {"key": "next line", "value": "\n"}
    ],
    "lastPresetName": "general-he",
    "lastSpeechSessionMode": "SMODE_DICTATION",
    "conversationPreferences": {"maxConversationSpeakers": 4}
  }'

import requests

response = requests.put(
    "https://koldan.dixilang.com/api/v1/desktop/self/preferences",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    json={
        "wordMapping": [{"key": "next line", "value": "\n"}],
        "lastPresetName": "general-he",
        "lastSpeechSessionMode": "SMODE_DICTATION",
        "conversationPreferences": {"maxConversationSpeakers": 4},
    },
)
response.raise_for_status()
print(response.json())
DesktopPreferencesResponse

Returns the complete, updated preferences record.

Status Description
200 OK Preferences updated.
400 Bad Request A supplied preference value or JSON type is invalid.
401 Unauthorized Access token is missing or invalid.
403 Forbidden Token does not include desktop:app:use.
404 Not Found No Desktop profile exists for the authenticated user.

Data Models

DesktopPreferencesResponse

Field Type Nullable Description
id integer No Preferences record identifier.
userUuid string (UUID) No User that owns these preferences.
preferences DesktopPreferences No Complete Desktop preference configuration.
DesktopPreferencesResponse
{
  "id": 47,
  "userUuid": "d198edd6-c55b-4b72-af22-02fd173e2fb0",
  "preferences": { "...": "..." }
}

DesktopPreferences

All fields are optional in an update. Omitting a field preserves its stored value.

Field Type Required in update Nullable in response Description
microphoneSettings MicrophonePreferences No No Audio input settings. New-user default: the default section.
outputPreferences OutputPreferences No No Text output settings. New-user default: the default section.
keyboardMapping KeyboardMapping No No Desktop keyboard shortcuts. New-user default: the default section.
wordMapping WordMapping[] No Yes Ordered spoken-text replacement rules. New-user default: no mappings. An empty array clears all mappings; a read can represent no mappings as null.
lastPresetName string No Yes Name of the most recently selected recognition preset. New-user default: unset.
soundPreferences SoundPreferences No Yes Session notification sounds. New-user default: unset; clients should treat this as disabled.
lastSpeechSessionMode string enum No Yes Most recently selected mode. One of: SMODE_UNSPECIFIED, SMODE_DICTATION, SMODE_CONVERSATION. New-user default: unset.
conversationPreferences ConversationPreferences No Yes Conversation-mode settings. New-user default: unset.

MicrophonePreferences

Field Type Required in section Nullable in response Description
enableMicrophoneRecording boolean No No Accepted but has no current effect. Default: false.
enableLoopbackRecording boolean No No Capture system loopback audio together with microphone audio. Default: false.
preferredDeviceName string No Yes Preferred input-device name. Default: unset.
alwaysUseDefaultDevice boolean Yes No Follow the operating system's default input device. New-user default: true.
startSessionToggle string enum Yes No Start shortcut behavior. One of: TOGGLE_DISABLED, TOGGLE_ENABLED. New-user default: TOGGLE_ENABLED.
philipsIntegrationPreferences PhilipsIntegrationPreferences Yes No Philips dictation-device settings. New-user default: enabled with start button 0.

PhilipsIntegrationPreferences

Field Type Required in section Nullable in response Description
enabled boolean Yes No Enable supported Philips device controls. New-user default: true.
startButtonId integer No No Device button ID that starts recording. Default: 0.

OutputPreferences

Field Type Required in section Nullable in response Description
method string enum Yes No Output target selection. One of: OM_FOLLOW_MOUSE_CURSOR, OM_WINDOW_TITLE_NAME_EXACT, OM_WINDOW_TITLE_NAME_CONTAINS. New-user default: OM_FOLLOW_MOUSE_CURSOR.
windowTitleNameExact string No Yes Exact window title used with OM_WINDOW_TITLE_NAME_EXACT. Default: unset.
windowTitleNameContains string No Yes Window-title substring used with OM_WINDOW_TITLE_NAME_CONTAINS. Default: unset.
pasteStrategy string enum Yes No Delivery method. One of: PS_SHIFT_INSERT, PS_CTRL_V, PS_TYPE_SIMULATE. New-user default: PS_SHIFT_INSERT.
pasteCase string enum Yes No Delivery timing. One of: PC_ON_FINAL_RESULT, PC_ON_SEGMENT_RESULT. New-user default: PC_ON_FINAL_RESULT.
simulateTrailingSpaceOrNewline boolean No No Simulate the trailing space or newline after output. Default: false.

KeyboardMapping

Field Type Required in section Nullable in response Description
startSessionCombo KeyboardCombination Yes No Start-session shortcut. New-user default: Shift+F5.
stopSessionCombo KeyboardCombination Yes No Stop-session shortcut. New-user default: Shift+F6.
pasteLastResultCombo KeyboardCombination Yes No Paste-last-result shortcut. New-user default: Shift+F7.

KeyboardCombination

Field Type Required in section Nullable in response Description
modifiers string enum[] No Yes Zero or more modifiers: MKEY_UNKNOWN, MKEY_CTRL, MKEY_SHIFT, MKEY_ALT. Omission means no modifiers and can be returned as null.
key string enum Yes No Primary key. See supported keys.

Supported key values

Group Values
Function KEY_F1 through KEY_F12
Navigation and editing KEY_DELETE, KEY_REMOVE, KEY_TAB, KEY_ESC, KEY_SPACE, KEY_ARROW_LEFT, KEY_ARROW_RIGHT, KEY_ARROW_UP, KEY_ARROW_DOWN, KEY_INSERT, KEY_HOME, KEY_END, KEY_PAGE_UP, KEY_PAGE_DOWN, KEY_SUPER, KEY_ENTER
Letters KEY_LETTER_A through KEY_LETTER_Z
Numbers KEY_NUMBER_0 through KEY_NUMBER_9
Other KEY_TILDE, KEY_UNKNOWN

WordMapping

Field Type Required Nullable in response Description
key string Yes No Spoken word or phrase to match.
value string Yes No Replacement text inserted into the result. Newlines and other whitespace are preserved.

SoundPreferences

Field Type Required in section Nullable in response Description
enableNotificationSoundOnStartAndStop boolean No No Play a sound when a speech session starts and stops. Default: false.

ConversationPreferences

Field Type Required in section Nullable in response Description
maxConversationSpeakers integer No No Maximum expected speakers for conversation mode. 0 leaves the value unspecified. Default: 0.

New-user defaults

Preference Default
Default input device Enabled
Loopback recording Disabled
Start shortcut toggle Enabled
Philips integration Enabled; start button 0
Output target Follow mouse cursor
Paste strategy Shift+Insert
Paste timing Final result
Start / stop / paste-last shortcuts Shift+F5 / Shift+F6 / Shift+F7
Word mappings None
Notification sounds Disabled
Last preset and last session mode Unset
Conversation maximum speakers Unspecified