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/…
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/.
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
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": {}
}
| Field | Meaning |
|---|---|
status | true on success, false on a handled failure |
message | The reason when status is false; null on success |
data | The payload. On a failure it is null or absent; some actions return no data at all on success |
Check status first, then unwrap data.
- A few endpoints put their payload beside
statusinstead of underdata; for examplenotifications/unread_countreturns{status, message, count}. - Sign-in answers carry a
sessionStatefield besidedata, 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:
| Parameter | Meaning |
|---|---|
query | Search text (see below); send it empty for no filter |
page | Page number, starting at 0 |
size | Items 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, aReferer) 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):
| HTTP | When |
|---|---|
| 401 | No session cookie or token, an expired or ended session, an unknown, expired or revoked API token |
| 403 | Your 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 |
| 413 | A 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.
Document the per-endpoint failure messages once the endpoint reference exists.