Response envelope
Every endpoint returns the same envelope.
{
"status": 0,
"message": "OK",
"data": {}
}
| Field | Meaning |
|---|
status | 0 on success; any non-zero value is an error |
message | OK, or a human-readable error description |
data | Present when the endpoint returns content |
Check status, not just the HTTP code. A request can return HTTP 200 with a non-zero status when the operation was understood and refused. Treat the pair together: the HTTP code describes the request, status describes the operation.
Namespaces
Discovery — hosts
| Method | Path | Purpose |
|---|
| GET | /hosts/ | List hosts |
| POST | /hosts/ | Register a host |
| PUT | /hosts/{hostId}/ | Edit a host |
| DELETE | /hosts/{hostId}/ | Delete a host and detach it from its tasks |
| DELETE | /hosts/ | Bulk delete |
| GET | /hosts/summary/ | Host counts and status rollup |
| GET | /hosts/offgrid/ | List off-grid hosts |
| POST | /hosts/offgrid/ | Register an off-grid host |
| POST | /hosts/import-csv/ | Start a CSV import |
| GET | /hosts/import-csv/status/{jobId}/ | Import progress |
| GET | /hosts/import-csv/queue/ | Pending imports |
| POST | /hosts/import-csv/cancel/{jobId}/ | Cancel an import |
Discovery — templates
| Method | Path | Purpose |
|---|
| GET | /template/ | List task templates |
| POST | /template/define/ | Define a template |
| PUT | /template/define/ | Update a template |
| POST | /template/clone/ | Clone a template |
| POST | /template/activate/ | Activate templates |
| POST | /template/inactivate/ | Deactivate templates |
| DELETE | /template/ | Delete templates |
| GET | /template/schemas/ | Sensor configuration schemas |
| GET | /template/schemas/list/ | Available sensor schemas |
A clone of a finalised template lands in draft. The lifecycle gate is deliberate: without it an unreviewed copy would be immediately assignable to hosts.
Discovery — tasks and deployment
| Method | Path | Purpose |
|---|
| GET | /tasks/ | List tasks |
| GET | /tasks/status | Task status rollup |
| POST | /tasks/assign-hosts/ | Bind hosts to a task |
| PUT | /tasks/assign-hosts/ | Update a task's host list |
| DELETE | /tasks/assign-hosts/ | Remove a task |
| POST | /deployment/ | Run a task against its hosts |
| GET | /deployment/history/ | Past runs for a task |
| GET | /deployment/cloud-servers/ | Cloud discovery targets |
| POST | /deployment/cloud-servers/ | Create a cloud target |
| PUT | /deployment/cloud-servers/{hostId}/ | Update a cloud target |
| DELETE | /deployment/cloud-servers/{hostId}/ | Delete a cloud target |
| POST | /deployment/cloud-servers/{hostId}/finalize/ | Finalise a draft target |
| GET / POST / PUT / DELETE | /deployment/cloud-servers/draft/… | Draft cloud targets |
| GET | /deployment/offgrid/ | Off-grid deployments |
| POST | /deployment/offgrid/bundle/ | Generate an off-grid bundle |
| PATCH | /deployment/offgrid/status/ | Update off-grid deployment status |
POST /deployment/ reports what the run actually delivered: requested, inserted, updated and skipped counts per host, alongside any errors. The skipped count is the only record of a document that failed validation, so read it rather than assuming a 200 means everything landed.
Discovery — off-grid import
| Method | Path | Purpose |
|---|
| POST | /offgrid/import | Import a result bundle produced on a disconnected network |
| GET | /offgrid/import/status/{taskId} | Import progress |
Discovery — integrations
| Method | Path | Purpose |
|---|
| GET | /integrations/ | List integrations |
| POST | /integrations/ | Add an integration |
| PUT | /integrations/{integrationId} | Update an integration |
| DELETE | /integrations/{integrationId} | Remove an integration |
| GET | /integrations/{name}/active | The active integration for a provider |
| POST | /crowdstrike/sync | Trigger a host synchronisation |
| GET | /crowdstrike/sync/status | Synchronisation status |
| GET | /crowdstrike/dedup | Hosts awaiting a duplicate decision |
| GET | /crowdstrike/dedup/count | Count of pending decisions |
| POST | /crowdstrike/dedup/{aid}/merge | Merge with an existing host |
| POST | /crowdstrike/dedup/{aid}/keep-separate | Keep as a distinct host |
| POST | /crowdstrike/dedup/bulk | Resolve several at once |
Ingestion processing
| Method | Path | Purpose |
|---|
| GET | /processDeposit/ | Deduplication engine status |
| POST | /processDeposit/ | Request a deduplication pass |
| GET | /processDeposit/findings/summary | Summary of the most recent findings |
| GET | /processDeposit/cert/{hostId} | A host's signing certificate |
| GET | /processDeposit/key/{hostId} | A host's test signing key |
A full pass requires a scan start time. A full pass resolves every material older than its bound, so a request that supplies scan_type: full without one is rejected with a 400 rather than resolving the inventory against an unknowable bound.
Cryptographic materials
| Method | Path | Purpose |
|---|
| GET | /cmhistory/ | Change feed across the inventory |
| GET | /cmhistory/{canonicalId} | One material's timeline |
| GET | /cmhistory/{canonicalId}/at | State at a point in time |
| GET | /cmhistory/{canonicalId}/diff | Field-level change between versions |
| GET | /cmtags/ | List tags |
| POST | /cmtags/ | Create a tag |
| GET | /cmtags/{tagId} | Read a tag |
| PUT | /cmtags/{tagId} | Rename a tag |
| DELETE | /cmtags/{tagId} | Delete a tag |
| GET / POST / PUT / DELETE | /cmtags/scopes… | Named tag expressions |
History is readable and never writable: no path in the API can modify or delete a history entry.
Analysis and policy
| Method | Path | Purpose |
|---|
| GET | /analytic/host-analysis/ | Per-host risk rollup |
| POST | /analytic/host-analysis-filtered/ | Per-host rollup under a filter |
| GET | /analytic/enterprise-analysis/ | Estate-wide rollup |
| GET | /policy/ | List policies |
| POST | /policy/ | Create a policy |
| GET | /policy/{policyId} | Read a policy |
| PUT | /policy/{policyId} | Update a policy |
| DELETE | /policy/{policyId} | Delete a policy |
| GET | /policy/algorithms | Algorithm families and their options |
| GET | /policy/standard-policy | Built-in standard baselines |
| POST / PUT / DELETE | /policy/standard-policy… | Manage baselines — administrator only |
Export
| Method | Path | Purpose |
|---|
| GET | /cyclonedx/export | Every type, time-bounded |
| GET | /cyclonedx/export/certificates | Certificates |
| GET | /cyclonedx/export/keys | Keys |
| GET | /cyclonedx/export/protocols | Protocol endpoints |
| GET | /cyclonedx/export/binary | Binaries |
| GET | /cyclonedx/export/sourcecode | Source-code findings |
Filters and field mappings are documented on the CycloneDX Export Specification page.
| Method | Path | Purpose |
|---|
| GET | /ui/dashboard/widgets | The widget catalogue |
| GET | /ui/dashboard/widgets/{wid} | One widget's definition and query schema |
| POST | /ui/dashboard/widgets/{wid}/data | Data for that widget, under the posted parameters |
| GET | /ui/layouts/user/{uid} | A user's dashboard layout |
| PUT | /ui/layouts/user/{uid} | Save a layout |
| GET | /ui/layouts/name/{name} | A named layout |
| POST | /ui/layouts/name/{name} | Create a named layout |
| GET | /ui/layouts/templates | Layout templates |
| POST / PUT / DELETE | /ui/layouts/templates… | Manage templates |
| PUT | /ui/layouts/templates/default | Set the default template |
| GET | /ui/layouts/menu/{menuName} | Menu definition |
| GET | /ui/utils/lastCMDocsInsertTime | Freshness of the inventory |
Every widget follows one pattern: GET its definition to learn its query schema, then POST parameters matching that schema to its /data path. Widget definitions live in the database, so the catalogue a deployment returns is the authoritative list for that deployment.
Administration
| Method | Path | Purpose |
|---|
| GET | /admin/users | List users |
| GET | /admin/users/search | Search users |
| GET | /admin/user/{uid} | Read a user |
| POST | /admin/user | Create or update a user |
| POST | /admin/bulk-user | Bulk create or update |
| DELETE | /admin/user/{uid} | Delete a user and revoke its sessions |
| PUT | /admin/{uid}/updateRoles | Change a user's roles |
| GET | /admin/roles | List roles |
| GET | /admin/roles/{roleId} | Read a role |
| GET | /admin/roles/search | Search roles |
| DELETE | /admin/roles/{roleId}/{uid} | Remove a user from a role |
| GET | /admin/permissions/catalogue | Every permission the product defines |
| GET | /admin/permissions/{uid} | A user's effective permissions |
| PUT | /admin/permissions | Replace the role-to-permission map |
| POST | /admin/{realm}/createUser | Create a user in a named realm |
| PUT | /admin/{realm}/{uid}/updateUser | Update a user in a named realm |
A role change takes effect on the live session rather than at next sign-in, and deleting a user revokes their sessions immediately. Both matter for offboarding.
Configuration
| Method | Path | Purpose |
|---|
| GET | /configs/active/config | The active configuration |
| POST | /configs/ | Create a configuration version |
| PUT | /configs/{version}/ | Update a version |
| GET | /configs/versions/ | List versions |
| GET | /configs/versions/{version} | Read a version |
| POST | /configs/activate/{version} | Activate a version |
| POST | /configs/diff/{v1}/{v2}/ | Compare two versions |
| POST | /configs/restart | Reload services |
| GET | /configs/ui-configuration | Console display settings |
| GET / PUT | /user-configs/ui-configs/{uid} | Per-user interface preferences |
Audit
| Method | Path | Purpose |
|---|
| GET | /audit/ | Query the audit trail |
| GET | /audit/{auditId} | One audit record |
| GET | /audit/facets | Available filter values |
| GET | /audit/export | Export as CSV |
Audit visibility is enforced on the server. The scope is merged into every query rather than passed by the client: administrators and auditors see everything, managers see everything but the audit domain itself, and a standard user sees only their own actions. A client cannot widen that by supplying its own actor filter.
Notifications
The notification and rule engine exposes its own namespace under /notifications/, covering rules, criteria, destinations, templates, delivery records, cases and health checks. It is the largest namespace in the API; see the Notification Engine page for the model and the interactive reference for the endpoint list.
Logging
| Method | Path | Purpose |
|---|
| POST | /logs | Sensor log submission from a discovery agent |
Authenticated with the host certificate token rather than a user session. Bounded per call in both element count and element size, redacted on receipt, and forwarded to the central log store so a scan is readable end to end.
