API Reference

API Reference

uControl Insight provides a REST API for programmatic access to asset data. The API is available at /api/v1/ relative to the application context path.

Authentication

The API supports three authentication methods:

Generating Tokens

• Integration Keys — sidebar → Integration Keys (ADMINISTRATOR only)
• User API Tokens — Profile page (requires API_USER role)

Response Format

All API responses use a standard envelope:

{
  "data": [ ... ],
  "meta": {
    "totalCount": 42,
    "page": 0,
    "size": 50
  }
}

Endpoints

Assets

Asset Search Parameters

Asset Response Fields

Each asset carries both a coarse category (the "Type" shown in the UI) and a fine-grained sub type (the historical assetType value), plus a virtual flag for host-like assets:

The same fields appear in the CSV / JSON exports (/api/v1/export/assets.csv, /api/v1/export/assets.json): columns assetCategory, assetSubtype, virtual were added alongside assetType.

Example Requests

# List all VMs and physical hosts
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://server/uControlInsight/api/v1/assets?type=VM,PHYSICAL_HOST"

# List every Host-category asset (physical, VM, hypervisor, container, server)
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://server/uControlInsight/api/v1/assets?category=HOST"

# Search by name
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://server/uControlInsight/api/v1/assets?q=webserver&type=VM"

# Get asset detail
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://server/uControlInsight/api/v1/assets/abc123-def456"

Topology

Query parameter: depth (1-5, default 2) — number of relationship hops to traverse.

Discovery Runs

AI diagnosis (requires ucontrol.ai.enabled=true on the server) returns a short explanation of why a scan had errors / failed, with likely causes and recommended actions:

{
  "data": {
    "runId": "…",
    "status": "OK",
    "summary": "SSH authentication fails on 10.0.2.0/24 — no configured credential matches that subnet.",
    "likelyCauses": ["The only SSH credential has match pattern 10.0.1.* which does not cover 10.0.2.*"],
    "recommendedActions": ["Add an SSH credential matching 10.0.2.*", "Re-run the scan and check the per-IP scan summary"],
    "confidence": "HIGH",
    "model": "claude-haiku-4-5",
    "createdAt": "2026-05-12T19:40:00"
  }
}

When AI is disabled, status is DISABLED; for a run that did not fail it is NOT_APPLICABLE; if no diagnosis has been generated yet it is NONE (POST to generate). The diagnosis is also generated automatically when a scan finishes with errors, and is shown on the Discovery Runs page and included in the Microsoft Teams alert.

Credentials

Asset Categories & Types

Valid values for the category filter (coarse "Type") and the fine-grained types (assetType / sub type) they group:

The type filter still accepts any of the fine-grained values above.

Swagger UI

Interactive API documentation is available at /swagger-ui.html relative to the application context path.

Asset Lifecycle Actions (May 2026)

Administrator endpoints for the asset-lifecycle workflow. Both require DISCOVERY_ADMIN or ADMINISTRATOR.

See the Asset Aging & Lifecycle page for the full lifecycle model.

Asset Response Fields (May 2026 additions)

Pagination & navigation links (May 2026)

List endpoints with page and size query parameters now return absolute navigation URLs in a links object so client integrations don't have to construct the next URL by hand. The links preserve every other query parameter the caller sent (filters, sort, custom size) so following next just works.

The change is additive — existing clients that ignore links continue to work.

Shape

{
  "data": [ ... ],
  "total": 446,
  "page": 0,
  "pageSize": 50,
  "links": {
    "first": "https://insight.example/api/v1/assets?status=ACTIVE&size=50&page=0",
    "next":  "https://insight.example/api/v1/assets?status=ACTIVE&size=50&page=1",
    "last":  "https://insight.example/api/v1/assets?status=ACTIVE&size=50&page=8"
  }
}

Each link is independently optional:

• page 0 → no prev
• last page → no next (consumer signal to stop following)
• single page → only first (with first == last)

Endpoints that emit full nav (first / prev / next / last)

Endpoints that emit only first (top-N, no offset)

These return up to a limit capped result set and have no “next page” concept — they always show only first in the links block:

• /api/v1/flow/top-talkers
• /api/v1/flow/conversations
• /api/v1/insights/… (AhaAi insight feeds)

Suggested integration pattern

response = http.get("/api/v1/assets?status=ACTIVE&size=200")
while True:
    process(response.data)
    next_url = response.links.get("next")
    if not next_url:
        break
    response = http.get(next_url)

Client doesn't need to track page manually or recompute URLs — just follow next until it's absent.

Bulk relationships (May 2026)

Avoids the per-asset N+1 pattern when an importer needs the full edge list. Each row carries both endpoints' display names + types so the importer doesn't need a second lookup against /api/v1/assets just to humanise the IDs.

Software → Host export — one call:

GET /api/v1/relationships?type=RUNS_ON&size=500

Returns every SOFTWARE→HOST edge in a single page (for any reasonable estate).

Computed root parent on every asset (May 2026)

Every /api/v1/assets response (list and detail) now includes a derived parent block when the asset is a child of another asset — so a 3rd-party importer can read the host id off a software row directly, without joining via /api/v1/relationships at all.

Shape:

{
  "id": "abc-123",
  "assetType": "SOFTWARE_PACKAGE",
  "displayName": "nginx",
  "assetCategory": "SOFTWARE",
  …
  "parent": {
    "id": "host-456",
    "displayName": "web01",
    "assetType": "SERVER",
    "assetCategory": "HOST",
    "via": "RUNS_ON"
  }
}

Root assets (PHYSICAL_HOST, NETWORK_DEVICE, PRINTER, CLOUD_ACCOUNT, VIRTUALIZATION_MANAGER, CLUSTER, FLOW_EXPORTER, UNKNOWN_ENDPOINT) have no parent field — the JSON omits it entirely (@JsonInclude(NON_NULL)).

Resolution rules (focal asset type → parent):

Performance: bulk-resolved per page. A page of N assets always costs exactly 2 extra SQL queries (one for the edges, one for the parent asset rows) regardless of N — no N+1.

Schema introspection — available attributes per asset type (May 2026)

Importers can fetch the list of fields and observed customAttributes keys for every asset type without trial-and-error against the data. Two endpoints:

• GET /api/v1/schema/asset-types — schema for every asset type
• GET /api/v1/schema/asset-types/{type} — schema for one asset type (e.g. /api/v1/schema/asset-types/SOFTWARE_PACKAGE)

Each entry contains:

Example fragment:

{
  "type": "SOFTWARE_PACKAGE",
  "category": "SOFTWARE",
  "label": "Software Package",
  "isRoot": false,
  "parent": { "via": "RUNS_ON", "direction": "OUT", "parentCategory": "HOST" },
  "typeFields": [
    { "name": "id",          "type": "string",  "description": "Stable UUID asset identifier" },
    { "name": "displayName", "type": "string",  "description": "Human-friendly label" },
    { "name": "vendor",      "type": "string?", "description": "Software vendor / publisher" },
    "..."
  ],
  "customAttributeKeys": ["install_date", "package_manager", "version"]
}

Use it when: building or maintaining a 3rd-party importer, generating ORM models from the API, or auditing which connector-specific keys are present in your environment (the keys list reflects your current dataset).

Filter by category: add ?category=HOST (or SOFTWARE, NETWORK, STORAGE, CLOUD, …) to scope the response to a single category. Case-insensitive. Unknown values return HTTP 400.

GET /api/v1/schema/asset-types?category=HOST
GET /api/v1/schema/asset-types?category=SOFTWARE

Bulk Export Endpoints

For exporting data into BI tools, ITSM CMDBs, spreadsheets, or for backup, the platform exposes paginated, streaming export endpoints. All responses include a Content-Disposition attachment header so browsers download rather than render. CSV fields follow RFC 4180 quoting; JSON is a single array streamed record-by-record so memory stays bounded for large estates.

Installed Software

Each row carries assetId, assetDisplayName and assetHostname so the parent asset can be looked up without a second API call. Sorted by asset name, then package name, for stable, diffable output.

Filters (all optional, combinable):

• ?assetId={uuid} — only rows for that asset
• ?publisher={name} — exact match, e.g. ?publisher=Microsoft
• ?packageManager={name} — e.g. ?packageManager=dpkg

# Full inventory (CSV)
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/software.csv" \
  -o software.csv

# Just one asset (JSON)
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/software.json?assetId=3eadf3af-6683-4a6a-aa9e-ea4eff6e755a"

# Everything Microsoft-published, CSV
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/software.csv?publisher=Microsoft"

Example CSV output (header + two rows):

assetId,assetDisplayName,assetHostname,packageName,version,publisher,installDate,packageManager
3eadf3af-6683-4a6a-aa9e-ea4eff6e755a,esx01.example.com,esx01,openssh-server,8.9p1-3,Canonical,2024-11-12,dpkg
3eadf3af-6683-4a6a-aa9e-ea4eff6e755a,esx01.example.com,esx01,nginx,1.24.0-2ubuntu7.1,Canonical,2024-11-12,dpkg

Running Processes

Snapshot of processes captured at the most recent connectorised scan of each asset. Same parent-linking convention. Sorted by asset name, then PID.

Filters (all optional, combinable):

• ?assetId={uuid} — only rows for that asset
• ?username={name} — exact match, e.g. ?username=root

# Every process on every asset, JSON
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/processes.json"

# Just root processes on one host, CSV
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/processes.csv?assetId=3eadf3af-6683-4a6a-aa9e-ea4eff6e755a&username=root"

Performance & pagination

All four endpoints stream results in batches of 500 rows over the response body — memory stays bounded regardless of estate size. For estates with hundreds of thousands of software rows, prefer JSON over CSV (smaller encoding) and pipe directly to a file or parser rather than buffering in memory client-side.

Auth

Standard API key (Authorization: Bearer ucm_…) — same as every other /api/v1/* endpoint. Requires the user to have the API_USER, DISCOVERY_ADMIN or ADMINISTRATOR role.

Synthesized asset types (CMDB-style)

Three asset types are returned by GET /api/v1/assets?type=… on demand from sub-record tables, so CMDB integrators get a uniform asset-shaped response without the platform needing to migrate that data into the main assets table:

Each synthesized row is a standard AssetSummaryResponse with:

• id — the sub-record UUID (stable across re-scans)
• assetType / assetCategory — the synthesized type / category
• displayName — the package / process / service name
• customAttributes — JSON bag of type-specific fields (install_date, pid, listen_ports, etc.)
• parent — {@link ParentRef} pointing to the host asset, with via=RUNS_ON so the relationship graph stays consistent

Filterable via the standard ?q= free-text search (matches against the package / process / service name, the asset display name, and the publisher / command line). Pagination via ?page= + ?size= mirrors the rest of the assets API.

# All software packages, page 1
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/assets?type=SOFTWARE_PACKAGE&page=0&size=50"

# All Microsoft software across the estate
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/assets?type=SOFTWARE_PACKAGE&q=Microsoft"

# Processes named nginx
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/assets?type=RUNNING_PROCESS&q=nginx"

# Discovered services
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/assets?type=DISCOVERED_SERVICE"

Example response (truncated):

{
  "data": [
    {
      "id": "8b2c1d3e-...",
      "assetType": "SOFTWARE_PACKAGE",
      "assetCategory": "SOFTWARE",
      "displayName": "openssh-server",
      "vendor": "Canonical",
      "model": "8.9p1-3",
      "customAttributes": "{\"install_date\":\"2024-11-12\",\"package_manager\":\"dpkg\"}",
      "status": "ACTIVE",
      "parent": {
        "id": "3eadf3af-6683-4a6a-aa9e-ea4eff6e755a",
        "displayName": "esx01.example.com",
        "assetType": "PHYSICAL_HOST",
        "assetCategory": "HOST",
        "via": "RUNS_ON"
      }
    }
  ],
  "page": 0, "size": 50, "totalElements": 1247
}

When to use which:

• Bulk dump for ETL / data warehouse → the dedicated /api/v1/export/software.csv et al. Streaming, lighter payload, simpler shape.
• CMDB sync / interactive queries / pagination → /api/v1/assets?type=…. Same response shape as every other asset, parent relationship baked in.

Discovered Services export

Mirror of the software / processes export pattern.

Filters: ?assetId={uuid}, ?state={state}.

# All services, JSON
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/services.json"

# Only running services on one asset
cu​rl -H "Authorization: Bearer ucm_yourkey" \
  "https://insight.example.com/uControlInsight/api/v1/export/services.csv?assetId=3eadf3af-6683-4a6a-aa9e-ea4eff6e755a&state=running"

Retention & aging behaviour for sub-records

The three sub-record types persist with different lifecycle rules — the API surface is identical (export + synthesized assets), but how rows accumulate and age out differs by type:

The behavioural difference matters for what you can ask of the data:

• Packages & services have stable identity per host. You can track "when was this package first installed?", "this service has been running uninterrupted for 90 days", or "a new package appeared on this server overnight". The row's id is stable across scans, so a CMDB integrator can subscribe to a specific row and have it stay valid.
• Processes are a snapshot. PIDs rotate, processes start and exit between scans, and there's no stable identity to age. The export and synthesized-asset views always reflect only the most recent scan. Asking "was nginx running yesterday?" is not a question the platform can answer for processes — by design.

The retention sweep runs daily at 02:15 UTC and once shortly after each application restart. Tunable via application.yml:

ucontrol:
  retention:
    sub-asset-days: 30        # how long to keep packages/services not observed
    cron: "0 15 2 * * *"      # when the sweep runs (UTC)

INTERFACE as a first-class CI

Interface rows can be queried directly as if they were assets, with the host attached as the parent CI. Same synthesis pattern used for SOFTWARE_PACKAGE / RUNNING_PROCESS / DISCOVERED_SERVICE — no data migration; the rows are mapped from the interfaces table on demand.

Interface-to-interface connections

Cross-asset edges between interfaces are derived in InterfaceTopologyStage of the normalization pipeline from two evidence sources:

Stored in the new interface_connections table with unique key (source_interface_id, target_interface_id, discovered_via) so the same edge confirmed via two evidence sources is kept as two rows — operators can see both pieces of corroboration.

Surfaced in the Interfaces tab on every asset detail page in a new Connected to column: each cell links to the neighbour asset and shows its port name (e.g. switch-core-1:Gi1/0/12), with the discovery source + VLAN in the tooltip.

Next phase (not yet shipped): render port-to-port edges on the asset topology graph instead of just chassis-to-chassis. The data is now there; the visualisation work remains.