REST API

Everything the Census console shows comes from a JSON API, and scripts and other tools (Power BI, a PSA or ticketing system, your own PowerShell) can use the same API with an API token.

API tokens#

Create a token under My account › API tokens (click your name at the top right):

Name: what uses it, e.g. Power BI or nightly export.
Read-only (recommended): the token can only read. Untick it only for scripts that must change something (create tickets, start scans…).
Expires: after 30, 90 or 365 days, or never.

The token (census_…) is shown once: store it like a password. It acts as your login: it can do what your role allows, nothing more, and it stops working when your login is deleted (or, for an Active Directory login, when the AD account is disabled). Tokens can't create other tokens or change passwords and two-step sign-in. Delete a token on the same page; administrators see and can delete every login's tokens under Logins & roles › API tokens. Changes made with a token appear in the audit log with the token's name. Wrong tokens count as failed sign-ins (too many from one address lock it out for a few minutes).

Calling the API#

Send the token in the Authorization header. Answers are JSON (UTF-8); errors come as {"error": "…"} with an HTTP status (400 wrong input, 401 bad/expired token, 403 not allowed, 404 not found, 429 too many failures).

curl -s https://census.corp.local:8443/api/assets?limit=10 \
  -H "Authorization: Bearer census_xxxxxxxxxxxxxxxx"

$h = @{ Authorization = "Bearer census_xxxxxxxxxxxxxxxx" }
$r = Invoke-RestMethod "https://census.corp.local:8443/api/assets?limit=500" -Headers $h
$r.assets | Select-Object name, ip, asset_type, os_name, serial

Census uses a self-signed certificate unless you set up Let's Encrypt. With the self-signed one, trust it on the calling computer, or add -k to curl / -SkipCertificateCheck to PowerShell 7 (only on a network you trust).

Windows PowerShell 5.1 has no -SkipCertificateCheck. The often-quoted ServerCertificateValidationCallback = { $true } fails in scheduled tasks and remote sessions ("There is no Runspace available…", shown as "An unexpected error occurred on a send"). This works everywhere (for that PowerShell session only):

Add-Type @"
using System.Net; using System.Security.Cryptography.X509Certificates;
public class CensusTrustAll : ICertificatePolicy { public bool CheckValidationResult(ServicePoint s, X509Certificate c, WebRequest r, int p) { return true; } }
"@
[Net.ServicePointManager]::CertificatePolicy = New-Object CensusTrustAll

To send text with accents from PowerShell 5.1, pass the body as UTF-8 bytes: -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($json)).

Changes use POST, PUT, PATCH or DELETE with a JSON body (Content-Type: application/json).

API description (OpenAPI)#

GET /api/openapi.json returns an OpenAPI 3.0 description of every console route: path, method, a one-line summary, which permission it needs, and the fields of the main records (asset, software, vulnerability finding, compliance result, ticket, deployment, report result). Any signed-in login or API token can read it. Import it into Postman, Insomnia, Swagger UI or Power BI to browse the API and build requests:

curl -s https://census.corp.local:8443/api/openapi.json \
  -H "Authorization: Bearer census_xxxxxxxxxxxxxxxx" -o census-openapi.json

It describes the version of Census you run. Routes used only by Census agents, remote scanners, the help desk portal and the sign-in steps (setup, two-step and Windows sign-in) are left out: they aren't meant for scripts.

Health and metrics#

GET /api/health needs no token: it answers whether the server and its database work (HTTP 200, or 503). With an administrator's token it adds details. GET /metrics serves Prometheus metrics once an administrator turns them on. See Monitoring.

Useful endpoints#

The console's own calls are all available (open the browser's developer tools › Network on any page to see the exact request, or read the API description). The ones most often used from scripts:

Request	Returns / does
`GET /api/me`	The login the token acts as (check that a token works).
`GET /api/assets`	Assets: `{"assets": [...], "total": n}`. Parameters: `q` (search text), `type` (asset type), `state` (`active` default, `archived`, `all`), `group` (group ID), `sort` + `desc=1`, `limit` (max 1000) + `offset` for paging, `cols` (extra columns, comma separated, as in the asset list's ▥ Columns: e.g. `ips,macs,link_speed,agent_version`; the values come in `extra`).
`GET /api/assets/{id}`	One asset with all inventory details.
`GET /api/assets/{id}/software`	Installed software of an asset.
`GET /api/assets/{id}/events`	The asset's change history.
`GET /api/export/assets.csv`	The asset list as CSV (same parameters as `/api/assets`).
`GET /api/software`	Software titles with install counts (`q`, `platform`, `status`, `limit`).
`GET /api/software/installs?name=…`	Which assets have a title installed.
`GET /api/reports`	Built-in reports (ID, title, category).
`GET /api/reports/{id}`	Runs a report: `{"report": …, "result": {"columns": [...], "rows": [[...]], "asset_ids": [...]}}`. Add `?format=csv` for CSV.
`GET /api/saved-reports` and `GET /api/saved-reports/{id}/run`	Your custom reports, and their results.
`GET /api/users`	Logins (administrators). `GET /api/directory` lists Active Directory / Entra users.
`GET /api/events`	Recent changes on all assets.
`GET /api/tickets`	Help desk tickets (`view`, `q`, `limit`). `POST /api/tickets` creates one: `{"subject": "…", "body": "…", "priority": "normal", "category": "…", "type": "…", "requester_email": "…", "asset_ids": ["…"]}` and answers `{"ticket": {"id": …, "number": …, …}}`; dispatching rules run on it like on any new ticket.
`POST /api/assets/{id}/rescan`	Rescans one asset now (Scan permission).
`POST /api/scan`	Scans addresses now: `{"spec": "192.168.1.0/24", "cred_ids": []}`.
`GET /api/deployments`, `GET /api/deployments/{id}`	Deployments and their per-asset results.

The API is the same one the console uses, so it changes with Census versions. Fields are added over time; existing fields are only renamed or removed when unavoidable, and such changes are listed in the release notes.