API and MCP
The API Licence lets other systems read and control your locations over the site network. A system signs in with an API key you make on the processor, and then works with locations, commands, schedules and connection status in one of two ways:
- REST. An ordinary web API. Use it from your own software, such as a building management system or a script. See REST API.
- MCP. The Model Context Protocol. Use it to give an AI assistant on your computer the same abilities, in plain language. See MCP.
Both use the same keys, the same permissions and the same licence rules. Anything a key can do through one it can do through the other.
Get started
- Check the processor has an API Licence and a Manager Licence or a User App Licence. See What you need.
- Create a key on Settings → Access → API keys. Copy it when it's shown: it can't be shown again.
- Call the REST API, or connect an AI assistant over MCP.
- If something is refused, see Licences and limits and the troubleshooting tables on the REST and MCP pages.
What a key can do
What a key can do depends on the permissions you give it when you make it. You choose a preset, Read only or Read and control, or tick the permissions one by one. See API keys.
| It can | Permission |
|---|---|
| List locations, read one, read its state, notifications and connections | See locations and what is happening in them |
| Read the status of your connections | See the status of connections |
| Check where commands have got to | See whether commands were delivered |
| Send commands to locations | Send commands to locations |
| List schedules and read one, and see what each location can be sent | See schedules, and what each location can be sent |
| Make, change and delete schedules | Create schedules, Change schedules, Delete schedules |
| Read stays, and send check-ins and check-outs through the Stay API | Read stays, Check in and check out |
What a key cannot do
A key never administers the processor. It can't reach settings, the licence, upgrades, backup and restore, certificates, Administrators, other API keys or anything else an Administrator does. The processor answers a key on any of those routes as it would answer a stranger: 401.
The same key also works on the Stay API, if it has the stay permissions. The stay API is part of the API Licence.
What you need
| You need | Why |
|---|---|
| An API Licence | It's what lets keys work. Without it every request with a key is refused with 423. |
| A Manager Licence or a User App Licence | They provide the locations, commands and schedules behind the keys. The API Licence does nothing on its own: with neither, every request is refused with 423. |
| The processor's admin HTTPS port | Keys are only taken there, over HTTPS. The port is 8443 unless you changed it. See Ports and network. |
With an API Licence and a User App Licence only, a key can read locations and run commands, but there are no schedules by key or by MCP: every schedule request is refused. See Licences and limits.
You can make keys before you buy the API Licence. They're refused until the licence is added, and then they work.
Where it can be reached from
Keys and the MCP endpoint work on the site network only. Your system has to reach the processor's admin HTTPS port directly, from the same network or one routed to it.
A service that runs on the internet, such as a hosted AI assistant, can't call a processor on your site network. Run the assistant on a computer on the site network.