Skip to main content
Version: 0.10

API overview

The console is a client of the same REST API you can call yourself. This page covers the conventions every endpoint follows; read it before calling the API, because two of them are unusual: requests are form-encoded, and most failures arrive with HTTP 200.

Base URL​

The API is served on the same host as the console, under /api/v1/:

https://<your-organization>.velumedge.com/api/v1/…
TODO

Confirm the hostname pattern of the hosted service. On a self-hosted deployment, use the address you open the console at.

The endpoint paths are listed in the backend's route table, grouped by area: auth/, profile/, ou/tenants/, ou/deployments/, users/, roles/, sensors/, assets/, dashboards/, integrations/, templates/, templates_schedule/, tasks/, scans/, reports/, wizard/, layouts/, modules/<module>/ and notifications/.

TODO

Publish a per-endpoint reference (parameters and response shapes) generated from the backend controllers.

Authentication​

Every endpoint except sign-in, sign-up and the public settings (auth/register/enabled, auth/captcha) needs either the session cookie set by auth/login or a personal API token in an Authorization: Bearer header. See Authentication.

Request encoding​

Requests are not JSON

Parameters are sent as form fields or query parameters, never as a JSON body:

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

Responses are JSON. Only requests are form-encoded.

Each endpoint accepts one method. Reads (…/list, …/get) are usually GET, changes are POST. Parameters that hold a list, such as role ids, are sent as a JSON array inside a single form field, for example roleIds=["<uuid>","<uuid>"].

# List users (GET, query parameters)
curl -G 'https://<host>/api/v1/users/list' \
-H "Authorization: Bearer $VELUM_TOKEN" \
--data-urlencode 'query=' \
--data-urlencode 'page=0' \
--data-urlencode 'size=50'

# Rename a tenant (POST, form-encoded)
curl -X POST 'https://<host>/api/v1/ou/tenants/update/info' \
-H "Authorization: Bearer $VELUM_TOKEN" \
--data-urlencode 'tenantId=<tenant-uuid>' \
--data-urlencode 'name=Northwind Ltd' \
--data-urlencode 'description=Production estate'

curl --data-urlencode sends application/x-www-form-urlencoded by default.

Response envelope​

Handled responses are wrapped in the same envelope:

{
"status": true,
"message": null,
"data": {}
}
FieldMeaning
statustrue on success, false on a handled failure
messageThe reason when status is false; null on success
dataThe payload. On a failure it is null or absent; some actions return no data at all on success

Check status first, then unwrap data.

Exceptions
  • A few endpoints put their payload beside status instead of under data; for example notifications/unread_count returns {status, message, count}.
  • Sign-in answers carry a sessionState field beside data, see Authentication.
  • Downloads (logos, avatars, generated reports, report templates, the CSV import template, asset field files) return the raw file with no envelope.

Ids​

Every id the API returns or accepts is a public id: a UUID such as 3f2b8c1e-5d7a-4e90-b6a1-0c9d2e7f4a15. This includes tenant ids, which also appear in console URLs (/t/<tenant-id>/…), user, role, sensor, scan and report ids. Ids are stable for the life of the object.

An id that is malformed, unknown or belongs to another organization is answered exactly like a missing object, with a handled failure. The API never reveals whether an id exists elsewhere.

Lists and pagination​

List endpoints return the total alongside the page:

{
"status": true,
"message": null,
"data": {
"size": 1284,
"data": [
{ "id": "3f2b8c1e-…" },
{ "id": "9a41d0c2-…" }
]
}
}

data.size is the total number of matching items, not the length of this page.

Paged endpoints take these parameters:

ParameterMeaning
querySearch text (see below); send it empty for no filter
pagePage number, starting at 0
sizeItems per page

The server caps size at 200 by default (a deployment can change it, see Limits). A larger value is not refused: it is served as the maximum, and data.size still tells you how many there are in total. A negative page is treated as 0. Some short lists (roles, tenants) are not paged.

Search text​

For lists of named objects (users, scan templates, schedules, scan history, integration instances), query is a case-insensitive substring match. The characters % and _ are matched literally, not as wildcards.

Asset lists are different: their query uses the asset query language, see Assets.

Tenant scoping and modules​

Endpoints that work on tenant data take a tenantId parameter (the tenant's public id). The call is refused if your account holds no tenant role in that tenant, or lacks the permission the action needs.

Module endpoints (/api/v1/modules/<module>/…) are additionally refused with HTTP 403 when the module is switched off for that tenant, whatever your permissions. See Modules.

Requests from other sites​

To stop other web sites acting with a signed-in user's cookie, the server refuses a state-changing request (any method except GET, HEAD, OPTIONS and TRACE) with HTTP 403 when the browser marks it as coming from another site:

  • Sec-Fetch-Site: cross-site, or
  • an Origin (or, without one, a Referer) that is not the console's own address.

A script or server-side client normally sends none of these headers and is not affected. If your client does send them (for example a browser extension, or a tool that copies a browser's headers), drop them or make them match the console address. Browser pages on other sites cannot call the API.

Errors​

Handled failures come back with status: false and a message you can show to a user, usually with HTTP 200:

{
"status": false,
"message": "Tenant name is occupied",
"data": null
}

Do not branch on the HTTP status alone; the envelope's status is the authoritative signal. A failed sign-in is the exception and arrives with HTTP 401 and the envelope.

Refusals before the endpoint runs use HTTP status codes and a standard error body that is not the envelope (its status field is the numeric HTTP code, and its message may be empty):

HTTPWhen
401No session cookie or token, an expired or ended session, an unknown, expired or revoked API token
403Your account is not Enabled; your global permissions do not cover the endpoint; the session is still owed a sign-in step (see Session states); the module is switched off for the tenant; a cross-site request
413A request body larger than the web server in front of the API accepts, see Limits. Files within that size but over a per-file limit are handled failures in the envelope

On a 401, sign in again rather than retrying with the same credentials.

TODO

Document the per-endpoint failure messages once the endpoint reference exists.

See also​