Skip to content

GitLab

Last edited by Daniel Martin
Page history

HTTP API

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:

  1. Controller - View and control the live service item and themes
  2. Core - Show/hide display, login and other info
  3. Plugins - Search and add service items
  4. 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 or previous.
  • 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 or song.

/controller/theme-level POST 🔒

Set the theme level

Details
  • Arguments
    • level - New theme level, either global, service or song.
  • 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.

/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.

/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 or preview.
  • 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 or desktop.
  • 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 or previous.
  • 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.