Local API
Use the power of the Lexicon Local API to connect other apps or services in no time.
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.
Every endpoint is documented in the API Reference at the bottom of this page: tracks and searching, playlists, Custom Tags, playback control, and what is currently playing or queued.
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 it in the Lexicon settings under Local API (in Lexicon v1.11 and older: under Integrations). The same page shows whether the API is running and on which port.
Authentication
Starting in Lexicon v1.12, every app needs the user's approval. Older versions of Lexicon have no authentication.
Asking the user for access
The first time your app connects, Lexicon shows the user a popup asking whether your app may use the API. Tell Lexicon your app's name in the X-Lexicon-App header, it is what the user sees in the popup and in the list of apps in the settings:
X-Lexicon-App: My Lexicon Tool
Without that header Lexicon uses the app parameter, and then the product name from the User-Agent header (python-requests/2.32 becomes python-requests).
The best way to ask is POST /v1/auth/pair with your app's name in the body. The request waits up to two minutes for the user to answer, and returns a token when they allow your app:
POST http://localhost:48624/v1/auth/pair
{ "name": "My Lexicon Tool" }
{ "data": { "token": "YOUR_APP_TOKEN" } }
Store the token and send it with every request from then on:
Authorization: Bearer YOUR_APP_TOKEN
Any other request without a token also brings up the popup and waits up to a minute for the answer. When the user allows your app, the request goes through and the response carries the token in the X-Lexicon-Token header. An app on the same computer as Lexicon that keeps sending its name without a token is let in after that too, but an app on another device always needs its token.
While the user has not answered, or closed the popup without choosing, the request is refused with HTTP status 401 and error code 10. Lexicon does not ask again about the same app for a minute, so do not retry in a tight loop. If the user blocks your app, every request is refused with HTTP status 403 and error code 6, without asking again. Lexicon only asks once per app name: once the user allowed your app, a request that gives its name without its token (or a second POST /v1/auth/pair) is refused with HTTP status 409 and error code 11, without a popup. So store the token. If your app lost it, the user removes your app in the settings, and then it can ask again. The user can block or remove your app at any time; its token then stops working.
The API token
For scripts and tools of your own, the user can copy the API Token from the Local API settings. A request with that token is always let in:
Authorization: Bearer YOUR_API_TOKEN
Tokens only work in the Authorization header, not in the query string or the JSON body. A wrong token counts as no token. If the user regenerates the API token, the old one stops working right away.
Web pages
A request from a browser (one with an Origin, Sec-Fetch-* or Referer header) never brings up the popup. A web page can only use the API with a token, and is otherwise refused with HTTP status 401 and error code 9. Without a token, connect to the API by IP address, localhost or the computer's own name: a request for any other host name is refused the same way.
Before your app is let in, a request from another device can send at most 64 KB; with a token the limit is 100 MB. A larger request is refused with HTTP status 413 and error code 12.
Network access
The API listens on every network interface, not only on localhost, so devices on the same network can use it too. They always need a token. In Lexicon v1.11 and older, any device that can reach your computer on the API's port, such as anything else on the same Wi-Fi, can read and modify your whole library without a password, and so can any website open in your browser.
Parameters
All query parameters can also be sent as a JSON body, even for GET requests. It does not work the other way around: only GET requests read the query string, so POST, PATCH and DELETE requests need a JSON body.
Query string parameter arrays and objects are in the following form:
Array: /tracks?fields=title&fields=artist
Object: /search/tracks?filter[artist]=Daft%20Punk&filter[title]=Touch
Array of objects, as URL-encoded JSON: /tracks?sort=[{"field":"title","dir":"asc"}]
or in bracket form: /tracks?sort[0][field]=title&sort[0][dir]=asc
Errors
A request that fails returns a JSON body with a message and an errorCode, usually with HTTP status 400. All error codes are listed under the Error schema in the API Reference.
You can send several requests at once. Requests that only read (GET) are answered right away, requests that change the library are handled one after another in the order they arrive. Older versions of Lexicon handle one request at a time and answer any request sent while another is still running with error code 2.
Getting started
You will find the API on your own computer at http://localhost:48624. From another device on the same network, use that computer's IP address instead of localhost. Starting in Lexicon v1.12, the user can change the port in the Local API settings, so let the user set it in your app too.
After enabling the API in the Lexicon settings, you can test this by sending a simple request: GET: http://localhost:48624/v1/tracks
With the following query string parameters or JSON body:
{
"limit": 10,
"offset": 0
}
This will return the first 10 tracks of your library. That is one of many endpoints, so have a look at the API Reference below for the rest.
Need help or have feedback?
You can get help or share your feedback or project with other Lexicon users on the forum or on Discord.
Missing something in the API? Let us know!