Developers

Use the power of the Lexicon Local API to connect other apps or create scripts for your own routine.

Unfinished content: The Lexicon Local API is under development

Lexicon has an API that other applications can use to get data out of Lexicon. You can get almost anything out of Lexicon, like your tracks, playlists, cues, beatgrids, tags, etc.

You can also directly query the Lexicon SQLite database, but it is not recommended to do so. You may run into locking issues while Lexicon is running, and you will have to join your own data. Unless you have a very specific use-case, you should always use the API first.

Enabling the API

The Lexicon Local API is a REST API that you can send requests to as long as Lexicon is running.

The API is disabled by default. You can enable the API in the Lexicon settings under Integrations.

Authentication

There is currently no authentication for the API, but this will change in the future.

Getting started

You will find the API on your local computer at http://localhost:48624.

You can test this by sending a simple request: GET: http://localhost:48624/v1/tracks

With the following JSON body:

{
  "limit": 10,
  "offset": 0
}

This will return the first 10 tracks of your library.

Endpoints

These are all the currently available endpoints.

All parameters are in the body of the request as JSON.

GET requests support a body and query string parameters. No other request methods support query string parameters.

Query string parameter arrays and objects are in the following form:

/search/tracks?filter.artist=Daft%20Punk&filter.title=Touch

/tracks?fields[0]=title&fields[1]=artist

GET: /v1/tracks

Get all tracks from the users' library.

Parameters:

Property Type Required Default Explanation
limit Number Yes Amount of tracks. Max 1000.
offset Number Yes Offset from start of tracks
source String No non-archived Source of tracks. Can be 'all', 'archived', 'non-archived' or 'incoming'
fields Array No null Fields to populate. Fewer fields will be more performant. Leave empty to populate all fields. See Fields below for available fields.

Example:

GET: /v1/tracks
Body: {
  "limit": 1000,
  "offset": 0,
  "source": "non-archived",
  "fields": ["title", "artist"]
}

GET: /v1/track

Gets one track from the users' library.

Parameters:

Property Type Required Explanation
id Number Yes Track ID

Example:

GET: /v1/track
Body: {
  "id": 123
}

PATCH: /v1/track

Updates one track in the users' library.

Parameters:

Property Type Required Explanation
id Number Yes Track ID
edits Track Yes Track object with updates

You can use most fields available in the Track object. Some fields are not editable, most of these fields belong to a file, such as location, bitrate, etc.

Number fields (eg playCount or energy) can accept a number and string value. A string value must always start with + or - and will change the value relative to the current value.

Date fields must be in the YYYY-MM-DD format.

Example:

PATCH: /v1/track
Body: {
  "id": 123,
  "edits": {
    "title": "My New Title",
    "energy": 10
  }
}

GET: /v1/playlists

Gets all playlists as a recursive tree. Does not include track IDs.

Does not have any parameters.

GET: /v1/playlist

Gets one playlist from the users' library. Includes track IDs for that playlist in original order.

Parameters:

Property Type Required Explanation
id Number Yes Track ID

Example:

GET: /v1/playlist
Body: {
  "id": 123
}

GET: /v1/playlist-by-path

Gets one playlist from the users' library. Includes track IDs for that playlist in original order. You don't need to know the playlist ID for this endpoint, only the path. This is very useful if you re-import your library since all IDs will be reset.

This returns the first playlist found with the given path. For more control, you can use the type parameter.

Parameters:

Property Type Required Default Explanation
path Array Yes The full path of a playlist
type Playlist Type No "2" (Normal playlist)

Example:

GET: /v1/playlist-by-path
Body: {
  "path": ["Music", "Techno", "Hits"],
  "type": "2"
} 

GET: /v1/tags

Returns all tags and tag categories.

This endpoint has no arguments.

GET: /v1/search/tracks

Search the users' library for tracks.

Parameters:

Property Type Required Default Explanation
source String No non-archived Source of tracks. Can be 'all', 'archived', 'non-archived' or 'incoming'
fields Array No null Fields to populate. Fewer fields will be more performant. Leave empty to populate all fields. See Fields below for available fields.
filter Track Yes The Track object with key values that are filtered on

The filter value is an object of type Track that can be filled with key values that Lexicon will filter on. Any unknown keys will be dropped. String filtering is always case insensitive and will match if the given string is anywhere inside the value. Number filtering input are strings and support number operators like > and >=, see the manual.

The location field is a special field that converts the input to a unique location before finding results. A unique location is a string that is: string normalized, unicode normalized, lowercased and for macOS has the main drive name prefixed. So a location like /Users/chris/Music/foo.mp3 is changed to /Volumes/Macintosh HD/chris/Music/foo.mp3. This is the basis of unique tracks in Lexicon.

Returns an array of tracks that match the given filter. There is a maximum of 1000 tracks in the result.

Example:

GET: /v1/search/tracks
Body: {
    "fields": ["title", "bpm", "location"],
    "filter": {
        "artist": "andy",
        "bpm": ">=174"
    }
}

POST: /v1/control

With the control endpoint, you can run commands in Lexicon. The Stream Deck plugin also uses this endpoint. If you want to create custom controls from outside Lexicon, this is what you should use.

Parameters:

Property Type Required Explanation
action String Yes One of the actions below
parameters Object No Depending on the action

Actions:

Action Parameters Explanation
Application_OpenSettings Open Settings
Application_OpenHelp Open Help
Application_ToggleWindow Toggle Window
Navigation_ToggleSidebar Toggle Sidebar
Navigation_OpenPanelCues Open Cues Panel
Navigation_OpenPanelGrid Open Grid Panel
Navigation_OpenPanelJump Open Jump Panel
Navigation_ExpandPlaylists Expand Playlists
Navigation_CollapsePlaylists Collapse Playlists
Navigation_SelectCurrentPlaying Select Current Playing
Application_OpenEditor Open Editor
Application_OpenTags Open Tags
Application_SetRating amount: 0-5 Set Rating
Application_SetColor color: <Color> (see Colors below) Set Color
Application_SetEnergy amount: 0-10 Set Energy
Application_SetDanceability amount: 0-10 Set Danceability
Application_SetPopularity amount: 0-10 Set Popularity
Application_SetHappiness amount: 0-10 Set Happiness
MusicPlayer_Play Play
MusicPlayer_Next Next
MusicPlayer_Pause Pause
MusicPlayer_Previous Previous
MusicPlayer_TogglePlay Play/Pause
MusicPlayer_Eject Eject
MusicPlayer_ToggleQuantize Toggle quantize
MusicPlayer_Cue Cue
MusicPlayer_CuePlay Cue Play
MusicPlayer_DeleteHotcue index: <Number> Delete Hotcue
MusicPlayer_CreateHotcue index: <Number> Create Hotcue
MusicPlayer_Hotcue index: <Number> Hotcue
MusicPlayer_TempomarkerSet Move marker to current position
MusicPlayer_TempomarkerFind Jump to next marker
MusicPlayer_TempomarkerAdd Add marker at current position
MusicPlayer_TempomarkerRemove Delete current marker
MusicPlayer_TempomarkerDoubleBpm Double current marker BPM
MusicPlayer_TempomarkerHalveBpm Halve current marker BPM
MusicPlayer_ToggleMetronome Toggle metronome
MusicPlayer_JumpBeats beats: <Number> (positive or negative) Jump forward/backward
MusicPlayer_JumpEnd Jump to end
Application_ApplyCuepointGeneratorTemplate Apply generator template
MusicPlayer_ApplyCueTemplate index: <Number> Apply cue template
Incoming_SelectedDone Mark selected done
Application_ArchiveSelected Archive selected tracks
CloudFileBackup_UploadSelected Upload selected tracks

Example:

POST: /v1/control
Body: {
  "action": "Application_SetRating",
  "parameters": {
    "amount": 3
  }
}

Fields

These fields are available for querying and will be returned from the API.

Track

Property Type Remarks
id Number Unique ID
type
title String
artist String
albumTitle String
label String
remixer String
mix String
composer String
producer String
grouping String
lyricist String
comment String
key String
genre String
bpm Number
rating Number
color Color (see Colors below)
year Number
duration Number
bitrate Number
playCount Number
location String
lastPlayed String ISO date string
dateAdded String ISO date string
dateModified String ISO date string
sizeBytes Number
sampleRate Number
fileType
trackNumber Number
energy Number
danceability Number
popularity Number
happiness Number
extra1 String
extra2 String
streamingService
streamingId
tags Number[] The ID of the tag. Use the /tags endpoint to retrieve all tags.
locationUnique String The unique unicode normalized location.
tempomarkers
cuepoints
fingerprint String
beatshiftCase
archived Number 0 or 1
archivedSince String ISO date string
incoming Number 0 or 1
importSource
data

Playlist

Property Type Remarks
id Number
name String
dateAdded String ISO date string
type Playlist Type
folderType Playlist Folder Type
parentId Number
position Number Index position in the parent playlist folder
tracks Array Array of track IDs in original (unsorted) order

Values

Colors

Color
Red_Dark
Red
Red_Light
Red_Orange
Orange
Beige
Yellow_Dark
Yellow
Lime
Green_Light
Green
Green_Dark
Teal
Aqua
Aqua_Dark
Blue_Light
Blue
Blue_Dark
Blue_Violet
Violet
Violet_Light
Magenta
Magenta_Dark
Magenta_Red
Grey_Light
Grey_Dark
Black
White

Playlist Types

Type Value Explanation
Folder "1" Playlist folder
Playlist "2" Normal playlist
Smartlist "3" Smartlist

Playlist Folder Types

Type Value Explanation
Normal folder null Normal playlist folder
Root Folder "1" Root folder. Always at the very top of the playlist tree. Can only exist once.
Lexicon Folder "2" Special folder that Lexicon uses as default folder to save playlists in.

Questions?

Missing something? Got a question? Please ask!