Skip to main content

API overview

The console is a client of the same public REST API you can call yourself. This page covers the conventions that hold for every endpoint; read it before the endpoint reference, because the conventions are unusual in two respects — request encoding and the response envelope.

Base path​

Every endpoint is namespaced under a version prefix:

https://<deployment-host>/api/v1/…

Request encoding​

Requests are not JSON

This is the most common source of confusion. The API accepts form encoding, not a JSON request body:

  • POST — application/x-www-form-urlencoded
  • GET — query-string parameters
  • Uploads — multipart/form-data

Responses are JSON. Only requests are form-encoded.

# Correct
curl -X POST 'https://<host>/api/v1/users/list' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'page=0' \
  --data-urlencode 'size=50' \
  --cookie-jar cookies.txt --cookie cookies.txt

Response envelope​

Every JSON response is wrapped in the same envelope:

{
  "status": true,
  "message": null,
  "data": {}
}
FieldMeaning
statustrue on success, false on a handled failure
messageHuman-readable error text when status is false; usually null on success
dataThe payload

So a client's first job on every response is to check status and unwrap data.

Two exceptions

A small number of endpoints put their payload at the top level of the envelope instead of under data — for example the unread-notification count returns {status, message, count}. And binary downloads (avatars, generated reports, CSV templates) are returned as raw file bodies with no envelope at all.

Lists and pagination​

List endpoints return a count alongside the page of items:

{
  "status": true,
  "message": null,
  "data": {
    "size": 1284,
    "data": [
      { "id": 1 },
      { "id": 2 }
    ]
  }
}

size is the total number of matching elements, not the length of this page — which is what you need to render a pager.

They accept a common set of parameters:

ParameterPurpose
queryFree-text search
pagePage index
sizePage size
Page indexing

Whether page is zero- or one-based varies by endpoint. Check the endpoint's reference entry rather than assuming.

Errors​

A handled failure returns status: false with a message safe to show a user:

{
  "status": false,
  "message": "The requested asset does not exist.",
  "data": null
}

Note that a handled failure may still arrive with HTTP 200 — the envelope's status is the authoritative signal, so do not branch on the HTTP status alone.

Validation failures additionally carry field-level detail keyed by field name, which is what lets a form highlight the offending input.

Tenant scoping​

Endpoints operating on tenant data take the tenant id as a parameter. A call carrying no tenant id, or one for a tenant your account has no tenant role in, is rejected.

Endpoint reference​

TODO

Generate the per-endpoint reference from the backend's urls.kt and its controllers, grouped by domain: auth and profile, tenants, deployments, users and roles, assets, fields, layouts, sensors, integrations, scans, reports and notifications.

See also​