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
}
}
These fields are available for querying and will be returned from the API.
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 |
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
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 |
Type | Value | Explanation |
---|---|---|
Folder | "1" | Playlist folder |
Playlist | "2" | Normal playlist |
Smartlist | "3" | Smartlist |
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!