CMDB & Asset Management

The Configuration Management Database (CMDB) is the backbone of the ITSM platform — it stores Configuration Items (CIs) representing every infrastructure asset, their attributes, and the relationships between them. The platform integrates with external CMDB sources (ServiceNow CMDB, OpsRamp, UEM platforms like Intune and SCCM) and maintains a unified asset graph with dependency mapping, health scoring, and impact analysis.

Core concepts

Every managed resource in your infrastructure is represented as a Configuration Item (CI). CIs are classified by category (hardware, software, network, service, application, database, storage, cloud, virtual, container, infrastructure) and tracked through lifecycle states (draft, active, maintenance, retired, disposed). CIs can be linked to each other through typed relationships (e.g. depends_on, hosts, runs_on, connects_to, member_of) to form a dependency graph used for impact analysis and service map visualization.

Assets extend CIs with financial tracking — procurement costs, depreciation schedules, warranty status, lease terms, and full lifecycle management from order through disposal with audit trails.

The configuration item model

The configuration item model contains all the information about a managed infrastructure resource, including its type classification, network identity, ownership, health score, discovery source, compliance posture, and external system references.

Properties

Name
id
Type
string
Description
Unique identifier for the configuration item.
Name
ci_number
Type
string
Description
Auto-generated human-readable CI number with category prefix (e.g. HW4K2MN001, NW4K2MN002).
Name
name
Type
string
Description
Display name for this configuration item.
Name
description
Type
string
Description
Optional detailed description of the CI.
Name
ci_type_id
Type
string
Description
Reference to the CI type definition that governs allowed attributes and states.
Name
category
Type
string
Description
Top-level classification. One of hardware, software, network, service, application, database, storage, cloud, virtual, container, infrastructure, or other.
Name
state
Type
string
Description
Lifecycle state of the CI. One of draft, active, maintenance, retired, disposed, or unknown.
Name
environment
Type
string
Description
Deployment environment. One of production, staging, development, test, dr, or sandbox.
Name
criticality
Type
string
Description
Business criticality level. One of critical, high, medium, or low.
Name
hostname
Type
string
Description
Network hostname of the CI.
Name
ip_address
Type
string
Description
Primary IP address.
Name
fqdn
Type
string
Description
Fully qualified domain name.
Name
location
Type
string
Description
Physical or logical location identifier.
Name
datacenter
Type
string
Description
Datacenter where the CI resides.
Name
region
Type
string
Description
Cloud or geographic region.
Name
owner_id
Type
string
Description
User ID of the CI owner.
Name
owner_group
Type
string
Description
Owning team or group name.
Name
attributes
Type
object
Description
Type-specific dynamic attributes (OS, CPU, RAM, firmware version, etc.) governed by the CI type schema.
Name
tags
Type
array
Description
Classification tags for filtering and grouping.
Name
health_score
Type
number
Description
Composite health score from 0-100, calculated from availability, performance, compliance, incident, and change factors.
Name
health_status
Type
string
Description
Derived health status. One of healthy, warning, critical, or unknown.
Name
compliance_status
Type
string
Description
Compliance posture. One of compliant, non_compliant, unknown, exempt, or pending_review.
Name
risk_level
Type
string
Description
Calculated risk level based on criticality, compliance, and health. One of critical, high, medium, low, or unknown.
Name
discovery_source
Type
string
Description
How this CI was discovered. Examples: manual, servicenow_cmdb, opsramp, uem_intune, uem_sccm, network_scan, agent, cloud_api.
Name
external_id
Type
string
Description
Identifier of this CI in the external source system.
Name
external_source
Type
string
Description
Name of the external source system.
Name
last_discovered_at
Type
timestamp
Description
Timestamp of the last discovery scan that found this CI.
Name
created_at
Type
timestamp
Description
Timestamp of when the CI was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the CI was last updated.
Name
org_id
Type
string
Description
Organization this CI belongs to.

GET/v1/cmdb/items

List configuration items

This endpoint allows you to retrieve a paginated list of all configuration items in your organization. By default, a maximum of twenty items are shown per page. Results can be filtered by category, state, environment, criticality, health status, discovery source, tags, and more. Supports full-text search across CI name, hostname, and IP address.

Optional attributes

Name
page
Type
integer
Description
Page number for pagination. Defaults to 1.
Name
page_size
Type
integer
Description
Number of items per page. Default is 20, maximum is 100.
Name
category
Type
string
Description
Filter by CI category: hardware, software, network, service, application, database, storage, cloud, virtual, container, or infrastructure.
Name
state
Type
string
Description
Filter by lifecycle state: draft, active, maintenance, retired, or disposed.
Name
environment
Type
string
Description
Filter by environment: production, staging, development, test, dr, or sandbox.
Name
criticality
Type
string
Description
Filter by criticality: critical, high, medium, or low.
Name
health_status
Type
string
Description
Filter by health status: healthy, warning, critical, or unknown.
Name
discovery_source
Type
string
Description
Filter by discovery source, e.g. servicenow_cmdb, agent, cloud_api.
Name
tags
Type
array
Description
Filter by one or more tags.
Name
search
Type
string
Description
Full-text search across name, hostname, IP address, and CI number.
Name
sort_by
Type
string
Description
Sort field: name, ci_number, created_at, updated_at, health_score, or criticality.
Name
sort_order
Type
string
Description
Sort direction: asc or desc. Defaults to desc.

Request

GET

/v1/cmdb/items

curl -G http://localhost:3000/v1/cmdb/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=10 \
  -d category=hardware \
  -d state=active \
  -d environment=production

Response

{
  "has_more": true,
  "total": 1482,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "id": "ci_7xKpQ2mR4wVb9nLs",
      "ci_number": "HW4K2MN001",
      "name": "prod-web-server-01",
      "description": "Primary web application server - US East",
      "ci_type_id": "type_3nLsW8kF9xYt",
      "category": "hardware",
      "state": "active",
      "environment": "production",
      "criticality": "critical",
      "hostname": "prod-web-01.dc1.example.com",
      "ip_address": "10.1.50.12",
      "fqdn": "prod-web-01.dc1.example.com",
      "location": "US-East-1",
      "datacenter": "DC1-Virginia",
      "region": "us-east-1",
      "owner_group": "Platform Engineering",
      "attributes": {
        "os": "Ubuntu 22.04 LTS",
        "cpu_cores": 16,
        "ram_gb": 64,
        "disk_gb": 500,
        "kernel_version": "5.15.0-91-generic"
      },
      "tags": ["web-tier", "load-balanced", "pci-scope"],
      "health_score": 94.5,
      "health_status": "healthy",
      "compliance_status": "compliant",
      "risk_level": "medium",
      "discovery_source": "agent",
      "external_id": null,
      "last_discovered_at": 1708732800,
      "created_at": 1706140800,
      "updated_at": 1708732800
    },
    {
      "id": "ci_9pRtH5jN2cEm4kWq",
      "ci_number": "NW4K2MN002",
      "name": "core-switch-dc1-01",
      "description": "Core L3 switch - DC1 aggregation layer",
      "ci_type_id": "type_8mWqR3nT5vXp",
      "category": "network",
      "state": "active",
      "environment": "production",
      "criticality": "critical",
      "hostname": "core-sw-01.dc1.example.com",
      "ip_address": "10.1.0.1",
      "fqdn": "core-sw-01.dc1.example.com",
      "location": "US-East-1",
      "datacenter": "DC1-Virginia",
      "region": "us-east-1",
      "owner_group": "Network Operations",
      "attributes": {
        "vendor": "Cisco",
        "model": "Nexus 9396PX",
        "firmware": "10.3(2)",
        "port_count": 48,
        "throughput_gbps": 2560
      },
      "tags": ["core-network", "spine", "pci-scope"],
      "health_score": 98.2,
      "health_status": "healthy",
      "compliance_status": "compliant",
      "risk_level": "medium",
      "discovery_source": "snmp",
      "external_id": "SNOW-CI0012345",
      "last_discovered_at": 1708732500,
      "created_at": 1706227200,
      "updated_at": 1708732500
    }
  ]
}

POST/v1/cmdb/items

Create a configuration item

This endpoint allows you to create a new configuration item. The CI type must exist and governs which attributes are required and which lifecycle states are valid. A unique CI number is auto-generated based on the category prefix.

Required attributes

Name
name
Type
string
Description
Display name for the configuration item.
Name
ci_type_id
Type
string
Description
The CI type definition to use.
Name
category
Type
string
Description
Top-level classification: hardware, software, network, service, application, database, storage, cloud, virtual, container, infrastructure, or other.

Optional attributes

Name
description
Type
string
Description
Detailed description of the CI.
Name
state
Type
string
Description
Initial lifecycle state. Defaults to draft.
Name
environment
Type
string
Description
Deployment environment: production, staging, development, test, dr, or sandbox.
Name
criticality
Type
string
Description
Business criticality: critical, high, medium, or low. Defaults to medium.
Name
hostname
Type
string
Description
Network hostname.
Name
ip_address
Type
string
Description
Primary IP address.
Name
location
Type
string
Description
Physical or logical location.
Name
datacenter
Type
string
Description
Datacenter identifier.
Name
region
Type
string
Description
Cloud or geographic region.
Name
owner_group
Type
string
Description
Owning team or group.
Name
attributes
Type
object
Description
Type-specific dynamic attributes.
Name
tags
Type
array
Description
Classification tags.
Name
external_id
Type
string
Description
ID in an external source system.
Name
external_source
Type
string
Description
Name of the external source system.

Request

POST

/v1/cmdb/items

curl -X POST http://localhost:3000/v1/cmdb/items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-db-primary-01",
    "ci_type_id": "type_5kPmN8rT2wXq",
    "category": "database",
    "description": "Primary PostgreSQL cluster node - US East",
    "state": "active",
    "environment": "production",
    "criticality": "critical",
    "hostname": "prod-db-01.dc1.example.com",
    "ip_address": "10.1.60.10",
    "location": "US-East-1",
    "datacenter": "DC1-Virginia",
    "owner_group": "Database Engineering",
    "attributes": {
      "engine": "PostgreSQL",
      "version": "16.2",
      "cpu_cores": 32,
      "ram_gb": 128,
      "storage_type": "NVMe SSD",
      "storage_gb": 2000,
      "replication": "streaming",
      "extensions": ["pgvector", "pg_stat_statements"]
    },
    "tags": ["database-tier", "primary", "pci-scope"]
  }'

Response

{
  "id": "ci_4kPmN8rT2wXq7xKp",
  "ci_number": "DB4K2MN003",
  "name": "prod-db-primary-01",
  "description": "Primary PostgreSQL cluster node - US East",
  "ci_type_id": "type_5kPmN8rT2wXq",
  "category": "database",
  "state": "active",
  "environment": "production",
  "criticality": "critical",
  "hostname": "prod-db-01.dc1.example.com",
  "ip_address": "10.1.60.10",
  "fqdn": null,
  "location": "US-East-1",
  "datacenter": "DC1-Virginia",
  "region": null,
  "owner_group": "Database Engineering",
  "attributes": {
    "engine": "PostgreSQL",
    "version": "16.2",
    "cpu_cores": 32,
    "ram_gb": 128,
    "storage_type": "NVMe SSD",
    "storage_gb": 2000,
    "replication": "streaming",
    "extensions": ["pgvector", "pg_stat_statements"]
  },
  "tags": ["database-tier", "primary", "pci-scope"],
  "health_score": null,
  "health_status": "unknown",
  "compliance_status": "unknown",
  "risk_level": "unknown",
  "discovery_source": null,
  "external_id": null,
  "last_discovered_at": null,
  "created_at": 1708733100,
  "updated_at": 1708733100
}

GET/v1/cmdb/items/:id

Get a configuration item

This endpoint allows you to retrieve a single configuration item by its ID. The response includes the full CI record with all attributes, health scoring data, compliance posture, and discovery metadata. Results are cached in Redis for 300 seconds.

Request

GET

/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs

curl http://localhost:3000/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "ci_7xKpQ2mR4wVb9nLs",
  "ci_number": "HW4K2MN001",
  "name": "prod-web-server-01",
  "display_name": "Web Server 01 (Production)",
  "description": "Primary web application server - US East",
  "ci_type_id": "type_3nLsW8kF9xYt",
  "category": "hardware",
  "subcategory": "rack_server",
  "state": "active",
  "state_reason": "Provisioned and deployed to production",
  "state_changed_at": 1706400000,
  "environment": "production",
  "criticality": "critical",
  "hostname": "prod-web-01.dc1.example.com",
  "ip_address": "10.1.50.12",
  "ip_addresses": ["10.1.50.12", "10.1.50.13"],
  "mac_address": "00:1A:2B:3C:4D:5E",
  "fqdn": "prod-web-01.dc1.example.com",
  "dns_names": ["prod-web-01.dc1.example.com", "web01.internal"],
  "location": "US-East-1",
  "building": "DC1-Main",
  "floor": "2",
  "room": "Server Hall A",
  "rack": "R14",
  "rack_position": "U22-U25",
  "datacenter": "DC1-Virginia",
  "region": "us-east-1",
  "availability_zone": "us-east-1a",
  "owner_id": "usr_8mWqR3nT5vXp",
  "owner_group": "Platform Engineering",
  "managed_by_group": "Infrastructure Ops",
  "supported_by_group": "L2 Server Support",
  "attributes": {
    "os": "Ubuntu 22.04 LTS",
    "cpu_cores": 16,
    "ram_gb": 64,
    "disk_gb": 500,
    "kernel_version": "5.15.0-91-generic",
    "manufacturer": "Dell",
    "model": "PowerEdge R750",
    "serial_number": "DELL-SVC-7X9K2M"
  },
  "tags": ["web-tier", "load-balanced", "pci-scope"],
  "labels": {
    "tier": "frontend",
    "cost-center": "CC-4200"
  },
  "health_score": 94.5,
  "health_status": "healthy",
  "health_factors": {
    "availability": { "score": 0.99, "uptime_percentage": 99.97 },
    "performance": { "score": 0.92, "cpu_usage": 42, "memory_usage": 58 },
    "compliance": { "score": 0.95, "policy_violations": 0 },
    "incidents": { "score": 0.88, "open_count": 0, "last_30_days": 2 },
    "changes": { "score": 0.96, "pending_count": 1, "failed_last_30_days": 0 }
  },
  "health_last_calculated_at": 1708732800,
  "compliance_status": "compliant",
  "compliance_score": 95.0,
  "risk_level": "medium",
  "discovery_source": "agent",
  "discovery_id": "disc_2kNpL7mS9wYr",
  "last_discovered_at": 1708732800,
  "reconciliation_status": "matched",
  "external_id": null,
  "external_source": null,
  "version": 14,
  "created_at": 1706140800,
  "updated_at": 1708732800
}

PATCH/v1/cmdb/items/:id

Update a configuration item

This endpoint allows you to perform a partial update on a configuration item. Only the fields you include in the request body will be updated. State transitions are validated — you cannot move a CI directly from draft to retired, for example. The CI version is incremented and an audit record is created.

Optional attributes

Name
name
Type
string
Description
Updated display name.
Name
state
Type
string
Description
New lifecycle state. Must be a valid transition from the current state.
Name
state_reason
Type
string
Description
Reason for the state change.
Name
environment
Type
string
Description
Updated environment.
Name
criticality
Type
string
Description
Updated criticality level.
Name
attributes
Type
object
Description
Updated dynamic attributes. Merged with existing attributes.
Name
tags
Type
array
Description
Updated tags (replaces existing tags).
Name
owner_group
Type
string
Description
Updated owning team.

Request

PATCH

/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs

curl -X PATCH http://localhost:3000/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "maintenance",
    "state_reason": "Scheduled kernel upgrade to 6.1 LTS",
    "attributes": {
      "kernel_version": "6.1.0-18-generic",
      "maintenance_window": "2024-02-24T02:00:00Z"
    },
    "tags": ["web-tier", "load-balanced", "pci-scope", "maintenance-window"]
  }'

Response

{
  "id": "ci_7xKpQ2mR4wVb9nLs",
  "ci_number": "HW4K2MN001",
  "name": "prod-web-server-01",
  "state": "maintenance",
  "state_reason": "Scheduled kernel upgrade to 6.1 LTS",
  "state_changed_at": 1708733400,
  "environment": "production",
  "criticality": "critical",
  "attributes": {
    "os": "Ubuntu 22.04 LTS",
    "cpu_cores": 16,
    "ram_gb": 64,
    "disk_gb": 500,
    "kernel_version": "6.1.0-18-generic",
    "maintenance_window": "2024-02-24T02:00:00Z"
  },
  "tags": ["web-tier", "load-balanced", "pci-scope", "maintenance-window"],
  "health_score": 94.5,
  "health_status": "healthy",
  "version": 15,
  "created_at": 1706140800,
  "updated_at": 1708733400
}

DELETE/v1/cmdb/items/:id

Delete a configuration item

This endpoint soft-deletes a configuration item. The CI must have no active relationships before it can be deleted — remove or reassign all relationships first. The CI record is marked as deleted and retained for audit purposes. An audit event is emitted.

Request

DELETE

/v1/cmdb/items/ci_4kPmN8rT2wXq7xKp

curl -X DELETE http://localhost:3000/v1/cmdb/items/ci_4kPmN8rT2wXq7xKp \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "ci_4kPmN8rT2wXq7xKp",
  "ci_number": "DB4K2MN003",
  "deleted": true,
  "deleted_at": 1708733600,
  "deleted_by": "usr_8mWqR3nT5vXp"
}

GET/v1/cmdb/items/:id/relationships

Get CI relationships

This endpoint returns all relationships for a configuration item — both upstream (where this CI is the target) and downstream (where this CI is the source). The response includes the relationship type, the linked CI summary, impact weight, and whether the relationship is on the critical path. Use this to build dependency graphs and understand blast radius.

Optional attributes

Name
direction
Type
string
Description
Filter by direction: source (outbound), target (inbound), or both. Defaults to both.

Request

GET

/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs/relationships

curl -G http://localhost:3000/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs/relationships \
  -H "Authorization: Bearer {token}" \
  -d direction=both

Response

{
  "ci_id": "ci_7xKpQ2mR4wVb9nLs",
  "ci_name": "prod-web-server-01",
  "data": [
    {
      "id": "rel_3nLsW8kF9xYt2mRq",
      "relationship_type": "runs_on",
      "forward_label": "runs on",
      "reverse_label": "hosts",
      "direction": "source",
      "target_ci": {
        "id": "ci_6jHtK4pR8uWn3kPm",
        "ci_number": "VM4K2MN005",
        "name": "esxi-host-dc1-04",
        "category": "virtual",
        "state": "active",
        "health_status": "healthy"
      },
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.85,
      "confidence_score": 1.0,
      "is_verified": true,
      "created_at": 1706400000
    },
    {
      "id": "rel_9pRtH5jN2cEm4kWq",
      "relationship_type": "depends_on",
      "forward_label": "depends on",
      "reverse_label": "depended on by",
      "direction": "source",
      "target_ci": {
        "id": "ci_4kPmN8rT2wXq7xKp",
        "ci_number": "DB4K2MN003",
        "name": "prod-db-primary-01",
        "category": "database",
        "state": "active",
        "health_status": "healthy"
      },
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.95,
      "confidence_score": 1.0,
      "is_verified": true,
      "created_at": 1706400000
    },
    {
      "id": "rel_2kNpL7mS9wYr5jHt",
      "relationship_type": "connects_to",
      "forward_label": "connects to",
      "reverse_label": "connected from",
      "direction": "source",
      "target_ci": {
        "id": "ci_9pRtH5jN2cEm4kWq",
        "ci_number": "NW4K2MN002",
        "name": "core-switch-dc1-01",
        "category": "network",
        "state": "active",
        "health_status": "healthy"
      },
      "strength": "normal",
      "is_critical_path": false,
      "impact_weight": 0.5,
      "confidence_score": 0.92,
      "is_verified": false,
      "created_at": 1707000000
    }
  ]
}

POST/v1/cmdb/items/:id/relationships

Add a CI relationship

This endpoint creates a relationship between two configuration items. Self-referencing relationships are not allowed. Duplicate relationships (same source, target, and type) are rejected. Relationship creation invalidates the service map and impact analysis caches.

Required attributes

Name
target_ci_id
Type
string
Description
The ID of the target configuration item.
Name
relationship_type_id
Type
string
Description
The ID of the relationship type definition.

Optional attributes

Name
strength
Type
string
Description
Relationship strength: strong, normal, or weak. Defaults to normal.
Name
is_critical_path
Type
boolean
Description
Whether this relationship is on the critical service path. Defaults to false.
Name
description
Type
string
Description
Description of this specific relationship instance.
Name
source_port
Type
string
Description
Network port on the source CI (e.g. 443, eth0).
Name
target_port
Type
string
Description
Network port on the target CI.
Name
protocol
Type
string
Description
Communication protocol (e.g. tcp, https, grpc).

Request

POST

/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs/relationships

curl -X POST http://localhost:3000/v1/cmdb/items/ci_7xKpQ2mR4wVb9nLs/relationships \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_ci_id": "ci_5kPmN8rT2wXq9nLs",
    "relationship_type_id": "reltype_depends_on",
    "strength": "strong",
    "is_critical_path": true,
    "description": "Web server depends on Redis cache cluster",
    "target_port": "6379",
    "protocol": "tcp"
  }'

Response

{
  "id": "rel_8mWqR3nT5vXp6jHt",
  "source_ci_id": "ci_7xKpQ2mR4wVb9nLs",
  "target_ci_id": "ci_5kPmN8rT2wXq9nLs",
  "relationship_type_id": "reltype_depends_on",
  "forward_label": "depends on",
  "reverse_label": "depended on by",
  "strength": "strong",
  "is_critical_path": true,
  "description": "Web server depends on Redis cache cluster",
  "target_port": "6379",
  "protocol": "tcp",
  "confidence_score": 1.0,
  "is_discovered": false,
  "is_verified": false,
  "created_at": 1708733700,
  "created_by": "usr_8mWqR3nT5vXp"
}

POST/v1/cmdb/sync

Trigger CMDB sync

This endpoint triggers a CMDB synchronization from an external source system. Sync jobs are enqueued via BullMQ and processed asynchronously. Supports incremental and full sync modes. The platform reconciles discovered CIs against existing records using hostname, IP, serial number, and external ID matching with configurable confidence thresholds.

Required attributes

Name
source
Type
string
Description
The external source to sync from. One of servicenow_cmdb, opsramp, uem_intune, uem_sccm, device42, netbox, or cloud_api.

Optional attributes

Name
scope
Type
string
Description
Sync scope: full, incremental, or delta. Defaults to incremental.
Name
categories
Type
array
Description
Restrict sync to specific CI categories, e.g. ["hardware", "network"].
Name
since
Type
timestamp
Description
Only sync records modified after this timestamp. Applies to incremental and delta scopes.
Name
auto_reconcile
Type
boolean
Description
Automatically reconcile discovered CIs above the confidence threshold. Defaults to false.
Name
reconciliation_threshold
Type
number
Description
Confidence threshold (0.0 to 1.0) for auto-reconciliation. Defaults to 0.85.

Request

POST

/v1/cmdb/sync

curl -X POST http://localhost:3000/v1/cmdb/sync \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "servicenow_cmdb",
    "scope": "incremental",
    "categories": ["hardware", "network", "virtual"],
    "since": 1708646400,
    "auto_reconcile": true,
    "reconciliation_threshold": 0.9
  }'

Response

{
  "sync_job_id": "sync_4kPmN8rT2wXq",
  "source": "servicenow_cmdb",
  "scope": "incremental",
  "categories": ["hardware", "network", "virtual"],
  "status": "queued",
  "auto_reconcile": true,
  "reconciliation_threshold": 0.9,
  "queued_at": 1708733800,
  "estimated_records": 1247
}

GET/v1/cmdb/sync/status

Get sync status

This endpoint returns the current sync status and history for all configured CMDB sources. The response includes the last sync timestamp, record counts, reconciliation statistics, and any errors encountered during the most recent sync for each source.

Request

GET

/v1/cmdb/sync/status

curl http://localhost:3000/v1/cmdb/sync/status \
  -H "Authorization: Bearer {token}"

Response

{
  "sources": [
    {
      "source": "servicenow_cmdb",
      "status": "idle",
      "last_sync_at": 1708732800,
      "last_sync_scope": "incremental",
      "last_sync_duration_ms": 48200,
      "records_synced": 1247,
      "records_created": 23,
      "records_updated": 184,
      "records_unchanged": 1040,
      "reconciliation": {
        "auto_matched": 198,
        "manual_review": 9,
        "conflicts": 2,
        "unmatched": 23
      },
      "errors": [],
      "total_syncs": 312,
      "failed_syncs": 4,
      "next_scheduled_sync": 1708819200
    },
    {
      "source": "uem_intune",
      "status": "syncing",
      "last_sync_at": 1708732200,
      "last_sync_scope": "full",
      "last_sync_duration_ms": null,
      "records_synced": null,
      "progress_percent": 62,
      "current_sync_job_id": "sync_9pRtH5jN2cEm",
      "total_syncs": 89,
      "failed_syncs": 1,
      "next_scheduled_sync": null
    },
    {
      "source": "agent",
      "status": "idle",
      "last_sync_at": 1708733100,
      "records_synced": 4821,
      "records_created": 0,
      "records_updated": 312,
      "records_unchanged": 4509,
      "errors": [],
      "total_syncs": 8640,
      "failed_syncs": 12,
      "next_scheduled_sync": 1708733400
    }
  ]
}

POST/v1/cmdb/discover

Run discovery scan

This endpoint triggers an on-demand network discovery scan to find configuration items across your infrastructure. Discovery supports multiple methods including agent-based, agentless (SSH/WMI/SNMP), cloud API, Kubernetes API, and Terraform state. Discovered CIs are placed in a reconciliation queue where they can be matched to existing records or created as new CIs.

Required attributes

Name
source_type
Type
string
Description
Discovery method. One of agent, agentless, snmp, ssh, wmi, cloud_api, kubernetes, terraform, ansible, servicenow, or custom.
Name
connection_config
Type
object
Description
Connection configuration for the discovery source (credentials, endpoints, etc.).

Optional attributes

Name
name
Type
string
Description
A name for this discovery scan.
Name
ip_ranges
Type
array
Description
IP address ranges to scan, e.g. ["10.1.0.0/16", "192.168.1.0/24"]. Applies to agentless and SNMP scans.
Name
categories
Type
array
Description
Restrict discovery to specific CI categories.
Name
auto_reconcile
Type
boolean
Description
Automatically reconcile discovered CIs above confidence threshold. Defaults to false.

Request

POST

/v1/cmdb/discover

curl -X POST http://localhost:3000/v1/cmdb/discover \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "snmp",
    "name": "DC1 Network Discovery",
    "connection_config": {
      "community_string": "encrypted:v1:abc123...",
      "snmp_version": "v3",
      "timeout_ms": 5000
    },
    "ip_ranges": ["10.1.0.0/16"],
    "categories": ["network", "hardware"],
    "auto_reconcile": true
  }'

Response

{
  "discovery_job_id": "disc_6jHtK4pR8uWn",
  "name": "DC1 Network Discovery",
  "source_type": "snmp",
  "status": "queued",
  "ip_ranges": ["10.1.0.0/16"],
  "categories": ["network", "hardware"],
  "auto_reconcile": true,
  "queued_at": 1708734000,
  "estimated_hosts": 2048
}

GET/v1/cmdb/topology

Get infrastructure topology

This endpoint returns the infrastructure topology as a graph of CIs and their relationships, suitable for visualization in service map dashboards. The response includes nodes (CIs with summary data and health status) and edges (relationships with type, direction, and impact weight). You can scope the graph to a specific root CI and control traversal depth. Results are cached in Redis for 300 seconds.

Optional attributes

Name
root_ci_id
Type
string
Description
Start the graph traversal from a specific CI. If omitted, returns the full organization topology.
Name
max_depth
Type
integer
Description
Maximum traversal depth from the root CI. Default is 3, maximum is 10.
Name
categories
Type
array
Description
Filter nodes to specific CI categories.
Name
include_inactive
Type
boolean
Description
Include CIs in non-active states. Defaults to false.

Request

GET

/v1/cmdb/topology

curl -G http://localhost:3000/v1/cmdb/topology \
  -H "Authorization: Bearer {token}" \
  -d root_ci_id=ci_7xKpQ2mR4wVb9nLs \
  -d max_depth=3

Response

{
  "root_ci_id": "ci_7xKpQ2mR4wVb9nLs",
  "max_depth": 3,
  "generated_at": 1708734200,
  "nodes": [
    {
      "id": "ci_7xKpQ2mR4wVb9nLs",
      "ci_number": "HW4K2MN001",
      "name": "prod-web-server-01",
      "category": "hardware",
      "state": "active",
      "criticality": "critical",
      "health_score": 94.5,
      "health_status": "healthy",
      "environment": "production",
      "depth": 0
    },
    {
      "id": "ci_4kPmN8rT2wXq7xKp",
      "ci_number": "DB4K2MN003",
      "name": "prod-db-primary-01",
      "category": "database",
      "state": "active",
      "criticality": "critical",
      "health_score": 97.1,
      "health_status": "healthy",
      "environment": "production",
      "depth": 1
    },
    {
      "id": "ci_5kPmN8rT2wXq9nLs",
      "ci_number": "CL4K2MN006",
      "name": "redis-cache-cluster-01",
      "category": "cloud",
      "state": "active",
      "criticality": "high",
      "health_score": 99.0,
      "health_status": "healthy",
      "environment": "production",
      "depth": 1
    },
    {
      "id": "ci_6jHtK4pR8uWn3kPm",
      "ci_number": "VM4K2MN005",
      "name": "esxi-host-dc1-04",
      "category": "virtual",
      "state": "active",
      "criticality": "critical",
      "health_score": 91.3,
      "health_status": "healthy",
      "environment": "production",
      "depth": 1
    },
    {
      "id": "ci_9pRtH5jN2cEm4kWq",
      "ci_number": "NW4K2MN002",
      "name": "core-switch-dc1-01",
      "category": "network",
      "state": "active",
      "criticality": "critical",
      "health_score": 98.2,
      "health_status": "healthy",
      "environment": "production",
      "depth": 1
    },
    {
      "id": "ci_2kNpL7mS9wYr4jHt",
      "ci_number": "ST4K2MN007",
      "name": "netapp-san-dc1-01",
      "category": "storage",
      "state": "active",
      "criticality": "critical",
      "health_score": 96.8,
      "health_status": "healthy",
      "environment": "production",
      "depth": 2
    }
  ],
  "edges": [
    {
      "id": "rel_9pRtH5jN2cEm4kWq",
      "source_ci_id": "ci_7xKpQ2mR4wVb9nLs",
      "target_ci_id": "ci_4kPmN8rT2wXq7xKp",
      "relationship_type": "depends_on",
      "forward_label": "depends on",
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.95
    },
    {
      "id": "rel_8mWqR3nT5vXp6jHt",
      "source_ci_id": "ci_7xKpQ2mR4wVb9nLs",
      "target_ci_id": "ci_5kPmN8rT2wXq9nLs",
      "relationship_type": "depends_on",
      "forward_label": "depends on",
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.85
    },
    {
      "id": "rel_3nLsW8kF9xYt2mRq",
      "source_ci_id": "ci_7xKpQ2mR4wVb9nLs",
      "target_ci_id": "ci_6jHtK4pR8uWn3kPm",
      "relationship_type": "runs_on",
      "forward_label": "runs on",
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.85
    },
    {
      "id": "rel_2kNpL7mS9wYr5jHt",
      "source_ci_id": "ci_7xKpQ2mR4wVb9nLs",
      "target_ci_id": "ci_9pRtH5jN2cEm4kWq",
      "relationship_type": "connects_to",
      "forward_label": "connects to",
      "strength": "normal",
      "is_critical_path": false,
      "impact_weight": 0.5
    },
    {
      "id": "rel_6jHtK4pR8uWn9pRt",
      "source_ci_id": "ci_4kPmN8rT2wXq7xKp",
      "target_ci_id": "ci_2kNpL7mS9wYr4jHt",
      "relationship_type": "depends_on",
      "forward_label": "depends on",
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.9
    },
    {
      "id": "rel_4kPmN8rT2wXq3nLs",
      "source_ci_id": "ci_6jHtK4pR8uWn3kPm",
      "target_ci_id": "ci_2kNpL7mS9wYr4jHt",
      "relationship_type": "depends_on",
      "forward_label": "depends on",
      "strength": "strong",
      "is_critical_path": true,
      "impact_weight": 0.8
    }
  ],
  "stats": {
    "total_nodes": 6,
    "total_edges": 6,
    "max_depth_reached": 2,
    "critical_path_edges": 5
  }
}