The platform · private development
Enable JavaScript for the API reference and playground. Download the API contract.
Three steps: create a credential in Virtum, call the API with it, then walk the result with the cursor. Every request reads one tenant — the one the credential was issued in.
In Virtum, open Settings → API credentials (the page lives at /api-credentials on the address you sign in to). Issuing needs the platform.api_credential.manage permission; seeing the list needs platform.api_credential.read.
/api-credentials
platform.api_credential.manage
platform.api_credential.read
Give the credential a name that says what will use it, tick only the scopes it needs (for this guide, fleet.read) and, ideally, an expiry. The token looks like vk_<prefix>_<secret>. It is shown once: Virtum stores only a hash of the secret, so it cannot show it again. Put it in your secret store or environment, never in source.
fleet.read
vk_<prefix>_<secret>
Just exploring? The playground issues a one-hour, read-only credential for you instead, and lists it on the same page so you can revoke it.
Set two variables in your shell, then call the fleet inventory. VIRTUM_ORIGIN is the address you use Virtum at, for example https://virtum.cloud.
VIRTUM_ORIGIN
https://virtum.cloud
export VIRTUM_ORIGIN="https://virtum.cloud" export VIRTUM_TOKEN="vk_..." # from step 1 curl --fail-with-body "$VIRTUM_ORIGIN/api/v1/fleet/assets?limit=10" \ -H "Authorization: Bearer $VIRTUM_TOKEN" \ -H "Accept: application/json"
const response = await fetch(`${process.env.VIRTUM_ORIGIN}/api/v1/fleet/assets?limit=10`, { headers: {Authorization: `Bearer ${process.env.VIRTUM_TOKEN}`, Accept: "application/json"}, }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const {data, meta} = await response.json(); console.log(data.length, "assets; next cursor:", meta.next_cursor);
import os import requests response = requests.get( os.environ["VIRTUM_ORIGIN"] + "/api/v1/fleet/assets", params={"limit": 10}, headers={"Authorization": "Bearer " + os.environ["VIRTUM_TOKEN"], "Accept": "application/json"}, timeout=30, ) response.raise_for_status() body = response.json() print(len(body["data"]), "assets; next cursor:", body["meta"]["next_cursor"])
<?php $ch = curl_init(getenv('VIRTUM_ORIGIN').'/api/v1/fleet/assets?limit=10'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('VIRTUM_TOKEN'), 'Accept: application/json'], ]); $body = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($status !== 200) { throw new RuntimeException("HTTP $status"); } echo count($body['data']).' assets; next cursor: '.var_export($body['meta']['next_cursor'], true).PHP_EOL;
data is a list of FleetAsset objects — an explicit projection, never a database row. meta.count is how many came back, meta.limit the page size applied, and meta.next_cursor the value to pass as ?cursor= for the next page (null on the last page). An empty data is a normal answer for a tenant with no active assets.
data
meta.count
meta.limit
meta.next_cursor
?cursor=
A 401 means the token is wrong, expired or revoked; a 403 names the scope it needed. See Errors.
401
403
Virtum