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:

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:

Example:

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

PATCH: /v1/track

Updates one track in the users' library.

Parameters:

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:

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:

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:

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:

Actions:

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

Playlist

Values

Colors

Playlist Types

Playlist Folder Types

Questions?

Missing something? Got a question? Please ask!