API usage information¶
Base URL¶
Base URL
https://spoilerinterface.com/interface (local: http://localhost/interface). All paths in
this documentation are appended to the base URL.
Reading an endpoint¶
Each endpoint starts with a bar showing its method and path, e.g. GET POST PUT DELETE WS (WebSocket). Below it, the Auth line says how to authenticate and which content type to send.
Authentication¶
Each endpoint page states which of the following modes it uses on its Auth: line.
| Mode | How it works |
|---|---|
| api_key | Log in with POST /login to get an api_key. Send it as the ?api_key= query parameter, or rely on the api_key cookie that /login sets (max_age 1800 seconds). The query parameter wins when both are present. |
| Device id + token | Device status and update pushes (e.g. POST /update/sensor) authenticate with the device's id and token, e.g. sensor_id + sensor_token. No api_key is needed. |
| None | Public endpoints such as /test, /version, /signup and /login. |
Accounts with two-factor authentication enabled finish logging in through /2fa/verify.
Request conventions¶
Endpoints accept parameters in one of three ways. Each endpoint page says which one applies.
| Style | Description |
|---|---|
| Form | application/x-www-form-urlencoded or multipart/form-data fields. |
| JSON | A JSON body with Content-type: application/json. |
| Query or JSON body | The same fields may be sent as query parameters or in a JSON body. If a field is present in both, the query parameter wins. |
Responses¶
All responses are JSON.
Success response¶
HTTP 200 with a success key. The value is a string, object or array depending on the endpoint.
A few endpoints return a bare object instead of the envelope (for example /login returns {"api_key": ...}); their pages say so.
Failed response¶
A failed key. The value is usually a string, sometimes an object.
The HTTP status is 401 when the message contains one of the following, and 400 otherwise:
Incorrect username/passwordTry to login again(e.g. an invalid or expiredapi_key)Incorrect device informationInvalid device information
An invalid or expired api_key does not always give a 401. The newer endpoints (2FA, settings,
MQTT, reports) reply 401 with "[Auth]: Failed to validate the api_key. Try to login again.".
Some older endpoints fail later with a different message and a 400, for example
{"failed": "[Profile]: Failed to get session information"}. Either way, log in again to get a
new key.
Validation errors¶
When a field has the wrong type or a required JSON field is missing, FastAPI returns HTTP 422 with a detail key:
{
"detail": [
{
"loc": ["body", "sensor_value"],
"msg": "value is not a valid float",
"type": "type_error.float"
}
]
}
Update rate limit¶
Device updates are limited by account type (Basic: once per 60 s, Start-up/Growth/Premium: once per 30 s, Enterprise: once per second; see /packages). An update sent too early is rejected with:
{
"failed": {
"message": "Please wait for the update period to lapse. Remaining time is: 29",
"remaining_time_sec": 29
}
}
Wait remaining_time_sec seconds before retrying.