Your park's API

UTP Connect has an API: a way for programs — your website, a Discord bot, a spreadsheet, anything a developer writes — to ask your park how it's doing. It's how your website shows "Lost Bearings: open, 318 laps today", or your Discord keeps a leaderboard up to date.

You don't write any code to set it up: you create a key in the administration, and hand it to whoever builds the tool. To see what it makes possible, look at the #bot-examples channel on our Discord: its cards are drawn from our demo park's API, every minute.

What it can do#

With any key, a program can read:

• Every ride, live: whether it is open or closed, and why: for maintenance, out of order; running, stopped by an emergency stop, or unknown while your server is offline; waiting, running or unloading; who operates it; how many guests stand in its station; how many laps it did today.
• Your shows: which one is running, where it has got to, and when each starts next on its schedule.
• Laps: the most ridden rides, the top riders — today, this week, this month or of all time — and any player's laps and rank.
• On-ride photos: the latest ones, with their pictures and the page their QR code opens.

With a Read and write key, it can also:

• start or stop a show, as /utp sequence start does;
• play a track on a player's phone, or stop it, as /utp audio send does;
• open or close a ride, as /utp ride availability does.

It never works a ride's machinery: dispatching, gates and emergency stops stay with an operator standing in the station. Closing a ride stops guests boarding it: whoever sits in the station is let off, and the ride's closing commands run.

Create a key#

1. In the administration, open Settings, and scroll down to API.
2. Under Keys, give the key a Name: the program that will use it — Website, Discord bot.
3. Choose its Access: Read, or Read and write if it must start shows, play tracks, or open and close rides.
4. Click Create a key, and copy it straight away: it is shown only once.

Then give the developer two things:

Everything else they need — every request, every field, examples — is in the API reference.

Keep an eye on your keys#

Each key in the list shows when it was created and when it was last used. Revoke the ones you no longer use: one key per program makes that easy.

A park holds up to 20 keys, and each can make 120 requests a minute — far more than a status page or a bot needs: once a minute is plenty to look live.

Being told instead of asking#

A program that asks every minute learns about an emergency stop a minute late. To be told the moment it happens — a lap ends, a photo is taken, a ride stops or closes, a show is coming up, your server goes away — add a webhook.

To show your park inside the game rather than on a website — a hologram above a queue, a menu of your rides — see Placeholders.