Present: the control API for Companion and other tools

Anything that can send a web request can press the keys where you run the slides: Companion, a script, a lighting desk. Each request is one press. It needs a surface's key, from Present's Settings, then Control surfaces, then Add a surface (control surfaces). Someone must have the service's slides open, live or in Practice: the API never starts a service by itself.

Send a press

• Address: https://app.praisepad.app/api/present/control
• Method: POST
• Header: Authorization: Bearer and the key (it starts pp_ctl_ and has 32 letters and digits after it)
• Header: Content-Type: application/json
• Body: {"command": "next"}

From a computer's terminal:

curl -X POST https://app.praisepad.app/api/present/control -H "Authorization: Bearer pp_ctl_YOUR_KEY" -H "Content-Type: application/json" -d '{"command": "next"}'

The commands

• next, previous: Space and ←.
• screen_off, logo, clear_words: the full stop, L and Esc. Each turns on or off, as its key does.
• section: kind is verse, chorus, bridge, tag or pre-chorus, with n from 1 to 9 if you like: {"command": "section", "kind": "verse", "n": 2}
• moment: the Moment on Shift and n: {"command": "moment", "n": 1}
• message: up to 120 letters of your own, with any markup taken out: {"command": "message", "text": "Parent of #42 to the nursery"}. Or one of your church's messages by its name, with its blanks in values: {"command": "message", "template": "Kids pickup", "values": {"number": "42"}}
• clear_message, marker (while the sermon records), instrumental.

With no presentation_id, a press goes to the one service whose slides are running, or, when none is, to the one open in Practice. To name one, add "presentation_id": the long code after /present/ in the address where you run its slides.

The answers

• 200: {"ok": true, "id": "…", "command": "next", "presentation": {"id": "…", "title": "Sunday Morning"}, "practice": false}. The first id is the press's own, to match it in your tool's log.
• 400: the body isn't right; error says what, like "Say which section: verse, chorus, bridge, tag or pre-chorus."
• 401: "That key isn't right. Copy it again from Present settings › Control surfaces.", or "That key isn't one of this church's control surfaces, or it was revoked."
• 404: "That presentation isn't this church's.", "Present isn't on for this church.", or a message name PraisePad doesn't know.
• 409: nobody has the slides open; or two services' slides are running (or, with none running, two are open in Practice), and presentations lists each one's id and title, to send as presentation_id.
• 429: "At most 10 presses a second. Wait a moment.", with Retry-After.
• 500 or 502: the press didn't get through. Try again.

What's on screen, for your buttons

GET https://app.praisepad.app/api/present/control/state, with the same Authorization header (add ?presentation= and the id to name one), answers:

{"presentation": {"id": "…", "title": "Sunday Morning"}, "open": true, "practice": false, "seenAt": "…", "live": {"block": "Great Is Thy Faithfulness", "label": "Verse 2", "slide": 3, "of": 7, "screen": "on", "cleared": false, "message": false, "recording": true, "next": "Morning by morning new mercies I see", "text": "Great is Thy faithfulness / O God my Father"}}

open is true while the slides are open on a computer, and live is null when they aren't. screen is on, off or logo. text is the words on screen as the room sees them (on a slide whose lines come one at a time, the lines so far), up to 120 letters, its lines joined by " / ", and null while the words are cleared. live can carry a few more fields, for PraisePad's own phone pages: leave them be. With no presentation named, it shows the service a press would go to, and answers 409 as a press does when there are two. Ask once a second at most.

A key presses keys and reads what's live, nothing more: it can't change the plan or read anything else. Anyone holding it can press your buttons, so keep it in the tool that uses it, and Revoke it when that tool leaves the booth.