The HTTP API can be used by external applications or web pages to communicate with OpenLP.
To know what the state of OpenLP is and when it changes, you should use the WebSockets server.
API versions
OpenLP 3.x.x supports both the first version of the API (v1), and the second version of the API (v2). The first version of the API is deprecated and may be removed in a future version of OpenLP.
This document outlines the preferred version of the API (v2).
Getting Started
OpenLP runs the API server on the same port as the OpenLP remote. This is port 4316
by default. To use the API, use the host name of the computer OpenLP is running on, and the port assigned to the web server (4316
by default). All endpoints in the v2 api are prefixed with /api/v2
.
For example, if OpenLP is running on a computer with the local IP 192.168.1.23
, then we can get a image of the live display by heading to the url: http://192.168.1.23:4316/api/v2/live-image
Note
The OpenLP server is only available on your local network. OpenLP does not perform any sort of port forwarding and the server is not capable of handling large loads. It is not recommended to expose the OpenLP server to the internet unless you know what you are doing.
Authentication
Some endpoints require authentication if a username and password has been added in the settings. To authenticate your application, send a POST
request to /api/v2/core/login
with a JSON body containing the username
and password
. That will return the authentication token which you need to put in your request header: Authorization: <authentication_token>
.
A endpoint that requires you to have been authenticated (if enabled) is marked with 🔒
.
Endpoints
All responses are in JSON format. To describe the structure of a JSON response, you'll see a tree view. A JSON response can contain any JSON data type, including [ ] JSON array, { } JSON object, St JSON string, TF JSON boolean and Nm JSON number.
To call a http route, prefix it with the appropriate address:
http://<host>:<port>/api/v2/<route>
The API endpoints are split into 4 categories:
- Controller - View and control the live service item and themes
- Core - Show/hide display, login and other info
- Plugins - Search and add service items
- Service - View and control the current service
Controller
The controller endpoints provide information about the live service item and theme information. It also allows changing slide and changing the theme.
/controller/live-items
GET
Returns details about the live service item.
Details
-
Arguments: N/A
-
Show Return Format
{} - Root of the response ├── [] audit: - List of legal information about the service item │ └── The strings are always in this order: │ [<title>, <authors_all>, <copyright>, <ccli_number>] ├── [] backgroundAudio: - List of audio files. ├── [] capabilities: - List of capabilities (number indexes). ├── {} data: - The data associated with the service item. │ └── This can contain anything but most commonly contains these attributes: │ "alternate_title", "authors", "ccli_number", "copyright", "title" ├── [] footer: - Footer strings, line by line. ├── TF fromPlugin: - If this service item came from a plugin. ├── TF isThemeOverwritten: - If this item provides it's own theme. ├── St name: - The name of the plugin that created this service item. ├── St notes: - Notes for this service item. ├── [] slides: - Slide data for this service item. │ └── {} - A slide list item │ ├── St chords: HTML formatted string containing chords. │ ├── St footer: HTML formatted footer text for this slide. │ ├── St html: HTML formatted slide with no chords. │ ├── St text: Plain text slide with no chords. │ ├── TF selected: If this is the selected slide. │ ├── St tag: The tag used to identify this verse. │ └── St title: Same as the service item title. ├── St theme: - This service item's selected theme, null if missing. ├── St title: - Service item title. └── St type: - Display type. └── Can be one of the following: "ServiceItemType.Text", "ServiceItemType.Image", "ServiceItemType.Command"
-
Notes - Returns an empty object (
{}
) if there is no active service item.
/controller/live-item
GET
Returns details about the live item with only the active slide.
Details
-
Arguments - N/A
-
Show Return Format
{} - Root of the response ├── [] audit: - List of legal information about the service item │ └── The strings are always in this order: │ [<title>, <authors_all>, <copyright>, <ccli_number>] ├── [] backgroundAudio: - List of audio files. ├── [] capabilities: - List of capabilities (number indexes). ├── {} data: - The data associated with the service item. │ └── This can contain anything but most commonly contains these attributes: │ "alternate_title", "authors", "ccli_number", "copyright", "title" ├── [] footer: - Footer strings, line by line. ├── TF fromPlugin: - If this service item came from a plugin. ├── TF isThemeOverwritten: - If this item provides it's own theme. ├── St name: - The name of the plugin that created this service item. ├── St notes: - Notes for this service item. ├── [] slides: - Array contains one slide (the selected slide). │ └── {} - A slide list item │ ├── St chords: HTML formatted string containing chords. │ ├── St footer: HTML formatted footer text for this slide. │ ├── St html: HTML formatted slide with no chords. │ ├── St text: Plain text slide with no chords. │ ├── TF selected: If this is the selected slide. │ ├── St tag: The tag used to identify this verse. │ └── St title: Same as the service item title. ├── St theme: - This service item's selected theme, null if missing. ├── St title: - Service item title. └── St type: - Display type. └── Can be one of the following: "ServiceItemType.Text", "ServiceItemType.Image", "ServiceItemType.Command"
-
Notes - Returns an empty object (
{}
) if there is no active service item.
/controller/show
POST
🔒
Go to the specified slide
Details
- Arguments
- id - The index of the slide to switch to. (0 based index)
- Returns
- On success - Status 204 (NO CONTENT)
- Missing slide id - Status 400 (BAD REQUEST)
/controller/progress
POST
🔒
Go to the specified slide
Details
- Arguments
-
action - Slide switch direction, either
next
orprevious
.
-
action - Slide switch direction, either
- Returns
- On success - Status 204 (NO CONTENT)
- Missing slide action - Status 400 (BAD REQUEST)
/controller/theme-level
GET
🔒
Get the theme level
Details
- Arguments - N/A
- Returns
- Status 200, returns a string,
global
,service
orsong
.
- Status 200, returns a string,
/controller/theme-level
POST
🔒
Set the theme level
Details
- Arguments
-
level - New theme level, either
global
,service
orsong
.
-
level - New theme level, either
- Returns
- On success - Status 204 (NO CONTENT)
- Missing level - Status 400 (BAD REQUEST)
/controller/themes
GET
Get a list of all themes
Details
- Arguments - N/A
- Return Format
[] - Root of the response, list of themes └── {} - A theme ├── St name: - The theme name. ├── TF selected: - If this is the selected theme (dependant on theme level). └── St thumbnail: - Base64 thumbnail encoded in a unicode string.
/controller/themes/<theme_name>
GET
Get a theme's data
Details
- Arguments
- theme_name (in url) - The name of a theme.
- Returns
- Status 200, returns theme's JSON data but file paths have been removed and
background_filename
now contains a css background string.
- Status 200, returns theme's JSON data but file paths have been removed and
/controller/live-theme
GET
Get the live theme's data
Details
- Arguments - N/A
- Returns
- Status 200, returns live theme's JSON data but file paths have been removed and
background_filename
now contains a css background string.
- Status 200, returns live theme's JSON data but file paths have been removed and
/controller/theme
GET
Get the name of the current theme
Details
- Arguments - N/A
- Returns
- Status 200, returns current theme's name as a string.
/controller/theme
POST
🔒
Sets the current theme
Details
- Arguments
- theme - The name of a theme.
- Returns
- Status 200, returns current theme's name as a string.
- Notes
- If invalid theme name, the black default will be used.
- The request will set the theme at the current theme level.
- Setting the theme at song level is not implemented and returns a 501.
/controller/clear/<controller>
🔒
Clears a controller
Details
- Arguments
-
controller (in url) - The name of the controller, only accepts
live
orpreview
.
-
controller (in url) - The name of the controller, only accepts
- Returns
- On success - Status 204 (NO CONTENT)
- Invalid controller - Status 404 (NOT FOUND)
- Notes
- Only clears the controller itself, the live display will not change.
Core
The core endpoints allow setting the display mode (show/hide), the login endpoint, a capture of the live display and information about OpenLP.
/core/display
POST
🔒
Displays or hides the live view
Details
- Arguments
-
display - A live view display mode. Can be one of these strings:
hide
,show
,blank
,theme
ordesktop
.
-
display - A live view display mode. Can be one of these strings:
- Returns
- On success - Status 204 (NO CONTENT)
- Invalid display - Status 400 (BAD REQUEST)
/core/plugins
GET
Get list of plugins that provide a search function
Details
- Arguments - N/A
- Return Format
[] - Root of the response, list of plugins └── {} - A plugin ├── St key: - The plugin's identification name. └── St name: - The plugin's name.
/core/system
GET
Gets information about OpenLP API system settings
Details
- Arguments - N/A
- Return Format
[] - Root of the response └── {} - A plugin ├── TF login_required: - Is authentication required. └── Nm websocket_port: - The websocket server port.
/core/login
POST
Login to allow use of api endpoints that require authentication
Details
- Arguments
- username - The server username
- password - The server password
- Returns
- On success - Status 200, format:
{} - Root of the response └── St token: - The server authentication token.
- Invalid login - Status 401 (Unauthorized)
- Missing request body - Status 400 (BAD REQUEST)
/core/live-image
GET
Get a screenshot of the live display
Details
- Arguments
- username - The server username
- password - The server password
- Return Format
{} - A plugin └── St binary_image: - Dispite the name, a unicode string is returned containing a base64 image (encoded in unicode).
Plugins
The plugins endpoints provide some universal functions for all plugins that provide media items.
/plugins/<plugin>/search?text=<search-phrase>
GET
🔒
Search a plugin's available service items
Details
- Arguments
- plugin (in url) - The target plugin.
- search-phrase (in url) - The string to search for.
- Returns
- Status 200, returns a list of results.
- Notes
- Relies on the plugins to provide results in the same format.
/plugins/<plugin>/add
POST
🔒
Add a service item to the service
Details
- Arguments
- plugin (in url) - The target plugin.
- id - Id of a service item from the plugin.
- Returns
- On success - Status 204 (NO CONTENT)
- Invalid id - Status 400 (BAD REQUEST)
/plugins/<plugin>/live
POST
🔒
Send a plugin service item to the live controller
Details
- Arguments
- plugin (in url) - The target plugin.
- id - Id of a service item from the plugin.
- Returns
- On success - Status 204 (NO CONTENT)
- Invalid id - Status 400 (BAD REQUEST)
/plugins/<plugin>/search-options
GET
Get the available search options for a plugin
Details
- Arguments
- plugin (in url) - The target plugin.
- Returns
- On success - Status 200, with search options in JSON format.
- Unsupported for plugin - Status 501 (NOT IMPLEMENTED)
- Notes
- Currently the only built in plugin that supports this is the bibles plugin.
- The bible plugin provides a bible specific API. It's return format is as follows:
{} - The root ├── St primary: - The current primary bible name. └── [] bibles: - A list of strings (bible names)
/plugins/<plugin>/search-options
POST
🔒
Set a plugin's search options
Details
- Arguments
- plugin (in url) - The target plugin.
- option - A search option for the plugin.
- Returns
- On success - Status 204 (NO CONTENT)
- Missing option - Status 400 (BAD REQUEST)
- Unsupported for plugin - Status 501 (NOT IMPLEMENTED)
- Notes
- Currently the only built in plugin that supports this is the bibles plugin
Service
The service endpoints provide information and controls for the current service.
/service/items
GET
List the service items in the service
Details
- Arguments - N/A
- Return Format
[] - Root of the response, list of all the service items └── {} - A service item ├── St ccli_number: - CCLI number, empty string if not applicable or missing. ├── St id: - Unique service item id. ├── TF is_valid: - False if a required file is missing. ├── St notes: - Notes for the service item. ├── St plugin: - The plugin that provides this service item. ├── TF selected: - If this service item is currently live. └── St title: - The service item's title.
/service/show
POST
🔒
Show an item from the service
Details
- Arguments
- id - Unique service item id.
- Returns
- On success - Status 204 (NO CONTENT)
- Missing id - Status 400 (BAD REQUEST)
/service/progress
POST
🔒
Progress to the next or previous service item
Details
- Arguments
-
action - Service progress action, can be
next
orprevious
.
-
action - Service progress action, can be
- Returns
- On success - Status 204 (NO CONTENT)
- Missing action - Status 400 (BAD REQUEST)
/service/new
GET
🔒
Create a new service
Details
- Arguments - N/A
- Returns
- On success - Status 204 (NO CONTENT)
- Notes
- Does not save the existing service.