API Reference
One API, endless possibilities.
Everything the WebUI does, it does through this API — so anything you can configure on the appliance you can configure from a script, a pipeline or a configuration-management tool.
This reference is generated from the appliance’s own OpenAPI description (API version 1.0.0), so it describes exactly the routes the appliance registers.
Base URL
The API is served over HTTPS on the same address and port as the WebUI. Every path in this reference is relative to https://appliance.example.com/api/v1 — replace the host with your appliance’s management address:
https://appliance.example.com/api/v1/<path>Authentication
A JWT from POST /token, or an API token.
Post your email and password — the same ones you log into the WebUI with — to /token to get a token, then send it on every other request:
TOKEN=$(curl -s -X POST "https://appliance.example.com/api/v1/token" \
-H "Content-Type: application/json" \
-d '{"email": "<email>", "password": "<password>"}' | jq -r .token)
curl -H "Authorization: Bearer $TOKEN" "https://appliance.example.com/api/v1/<path>"An API token created in the WebUI works in the same header. The handful of endpoints that need no token say so on their own entry.
Requests and replies
Request and response bodies are JSON. Every reply has the same three fields: status, a human-readable message, and data — the payload, which is an object for one thing and an array for a list:
{
"status": "success",
"message": "Backends",
"data": []
}Each endpoint uses the method that matches what it does:
| Method | What it does |
|---|---|
|
Read one or more objects. |
|
Create an object. |
|
Update an object, or perform an action on it. |
|
Update part of an object. |
|
Remove an object. |
Applying changes
As in the WebUI, a configuration change is staged: it takes effect when you apply it. Send PUT /services/apply once you have made your changes, and the affected services restart.
Errors
The request was rejected. The body names what was wrong. Every endpoint can answer this way, so check the status code before reading a reply as data.
{
"status": "error",
"message": "<message>",
"error": {}
}The API in the manual
For how the API fits into the appliance — the port it listens on, the WebUI settings that affect it and worked examples — see the manual’s API chapter.