Skip to content

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.

{
    "success": "You have been Spoiled"
}

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.

{
    "failed": "Incorrect username/password! or user does not exists"
}

The HTTP status is 401 when the message contains one of the following, and 400 otherwise:

  • Incorrect username/password
  • Try to login again (e.g. an invalid or expired api_key)
  • Incorrect device information
  • Invalid 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.