🗄️ REST API: CMDB

The complete usage guide for the CMDB module of the REST API — classes, typed properties, configuration items, relationships, impact analysis and ticket links. Mirrors the interactive documentation at System → API → Documentation (with its live "Try it" tester).

[!NOTE] New to the API? The basics table on REST API: Tickets covers base URL, authentication, the response envelope, error codes, rate limits and PATCH semantics — identical across all modules.

What's distinctive about the CMDB:

🧬 Schema-driven	Every class defines typed properties (text, number, date, boolean, dropdown, object_ref). Read the class first (GET /cmdb/classes/{id}), then write objects with a friendly property_key → value map — the API validates types, required flags, dropdown options and object_ref target classes.
🌳 Hierarchy + graph	Objects nest via parent_id (cycle-guarded) and connect via directed relationships with verb/inverse-verb pairs ("depends on" / "is depended on by").
💥 Deletes take the tree	Deleting an object removes its whole descendant tree, properties, relationships and ticket links (the module's design). Check GET .../impact first — the response tells you deleted_descendants.
🛡️ Ticket links are company-scoped	The internal CMDB screen reads linked tickets unscoped (a known multi-tenancy gap); the API deliberately does not reproduce that — GET /cmdb/objects/{id}/tickets honours the key's company scope, and link/unlink gate the ticket.
🎛️ Classes are read-only in v1	Class design (properties, options, icons) stays an admin activity in the UI; the API reads definitions so integrations can build valid writes.

---

🚀 Quick start

Discover the shape, then create a CI with validated properties:

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# 1. What does a "server" need?
curl -s -H "$K" "$B/cmdb/classes" | jq '.data[] | {id, class_key, name}'
curl -s -H "$K" "$B/cmdb/classes/12" | jq '.data.properties[] | {property_key, type, is_required}'

# 2. Create it (required properties enforced; dropdowns validated against the option list)
curl -s -X POST "$B/cmdb/objects" -H "$K" -H "Content-Type: application/json" -d '{
  "name": "SQL01", "class_key": "server",
  "properties": { "hostname": "sql01.corp.local", "os": "Windows Server 2022" }
}'

# 3. Wire it into the graph
curl -s -X POST "$B/cmdb/objects/44/relationships" -H "$K" -H "Content-Type: application/json" \
  -d '{"to_object_id": 12, "verb": "depends on"}'

---

🧬 Classes

🟢 GET /cmdb/classes   🔑 cmdb_classes.read

All CI classes with class_key, icon, active flag and object counts.

🟢 GET /cmdb/classes/{id}   🔑 cmdb_classes.read

The class plus its full property definitions — everything needed to build a valid write:

{ "data": { "id": 12, "class_key": "server", "name": "Server",
    "properties": [
      { "id": 40, "property_key": "hostname", "label": "Hostname", "type": "text",
        "is_required": true, "target_class": null, "options": [] },
      { "id": 41, "property_key": "os", "label": "OS", "type": "dropdown",
        "is_required": false, "target_class": null,
        "options": [ { "value": "Windows Server 2022", "colour": null }, … ] } ] } }

---

🗄️ Objects

🟢 GET /cmdb/objects — list / search   🔑 cmdb_objects.read

Parameter	Description
class_id / class_key	Filter by class
q	Search by name
parent_id	Children of an object · top_level=true for roots
is_planned	true / false — planned vs live CIs
sort	name (default), id, created_at, updated_at — prefix - for descending
page / per_page	Pagination — default 1 / 25, max 100

🔵 POST /cmdb/objects — create   🔑 cmdb_objects.create

name + class_id/class_key required. properties is a map keyed by property_key. Validation mirrors the UI exactly — plus one improvement:

• required properties enforced on create (422 naming the missing label)
• number must be numeric · date must parse (ISO 8601) · boolean coerces sensibly
• object_ref must exist, can't self-reference, and must match the property's target class
• dropdown values must be one of the property's options (the UI stores anything — the API doesn't)

The class is immutable after creation, like the UI. Returns 201.

🟢 GET /cmdb/objects/{id} — get one   🔑 cmdb_objects.read

Fully hydrated: every class property with its typed value (object_ref values come with an embedded {id, name, class_name} card), parent, children, relationships.outgoing/incoming with natural-reading verbs, and the cached ai_summary.

🟠 PATCH /cmdb/objects/{id} — update   🔑 cmdb_objects.update

Update name, parent_id (existence + cycle-walk guard — you can't parent an object to its own descendant), is_planned, and any subset of properties — only the keys you send are touched (required checks apply only to sent properties, matching the UI's inline edit). Empty/null clears a property.

🔴 DELETE /cmdb/objects/{id} — delete   🔑 cmdb_objects.delete

[!WARNING] Takes the whole tree. The object, all its descendants, their property values, relationships and ticket links are permanently removed (object_ref properties elsewhere that pointed at them are cleared). The response reports deleted_descendants — run GET .../impact first if you're not sure.

🟢 GET /cmdb/objects/{id}/impact — impact analysis   🔑 cmdb_objects.read

The blast radius before you touch something:

{ "data": { "descendants": [ { "id": 45, "name": "NODE1", "class_name": "Server", "depth": 1 } ],
    "referenced_by_property": [ { "id": 7, "name": "Payroll", "class_name": "Application", "property": "Runs on" } ],
    "incoming_relationships": [ { "id": 45, "name": "NODE1", "class_name": "Server", "relationship": "is depended on by" } ] } }

---

🔗 Relationships

🔵 POST /cmdb/objects/{id}/relationships   🔑 cmdb_relationships.create

Creates a directed edge from this object: {"to_object_id": 12, "verb": "depends on"} (or relationship_type_id). No self-links (422); the same from/to/type triple twice → 409. The other side automatically reads with the inverse verb.

🔴 DELETE /cmdb/objects/{id}/relationships/{rel_id}   🔑 cmdb_relationships.delete

Removes the edge — it must involve this object (either direction).

---

🎫 Ticket links

🟢 GET /cmdb/objects/{id}/tickets   🔑 cmdb_ticket_links.read

The tickets linked to this CI — scoped to the key's companies (deliberately tighter than the internal endpoint).

🔵 POST /cmdb/objects/{id}/tickets   🔑 cmdb_ticket_links.create

Body: {"ticket_id": 141}. The ticket must be within the key's company scope (404 otherwise); already linked → 409.

🔴 DELETE /cmdb/objects/{id}/tickets/{ticket_id}   🔑 cmdb_ticket_links.delete

Removes the link.

---

📚 Reference data

Endpoint	Permission	Returns
🟢 GET /cmdb-relationship-types	🔑 reference.read	Verb + inverse-verb pairs (seeded: depends on, connects to, managed by)

---

🧪 Worked example: discovery-tool sync

A network-discovery job upserting CIs and wiring dependencies (cmdb_classes: read + cmdb_objects: read/create/update + cmdb_relationships: create):

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# Upsert-by-name within the server class
ID=$(curl -s -H "$K" "$B/cmdb/objects?class_key=server&q=sql01" | jq -r '.data[0].id // empty')
if [ -n "$ID" ]; then
  curl -s -X PATCH "$B/cmdb/objects/$ID" -H "$K" -H "Content-Type: application/json" \
    -d '{"properties": {"os": "Windows Server 2022"}}'
else
  ID=$(curl -s -X POST "$B/cmdb/objects" -H "$K" -H "Content-Type: application/json" \
    -d '{"name":"SQL01","class_key":"server","properties":{"hostname":"sql01.corp.local"}}' | jq -r '.data.id')
fi

# The app depends on the freshly-synced server
curl -s -X POST "$B/cmdb/objects/$APP_ID/relationships" -H "$K" -H "Content-Type: application/json" \
  -d "{\"to_object_id\": $ID, \"verb\": \"depends on\"}"

And change-risk enrichment — what breaks if we reboot this?

curl -s -H "$K" "$B/cmdb/objects/$ID/impact" \
  | jq -r '.data.incoming_relationships[] | "\(.class_name): \(.name) (\(.relationship))"'

---

Under the hood: REST API — How It Works · Other modules: Tickets · Assets · Problems · Changes · Knowledge · Tasks · Keys & permissions: System → API (System module) · Module docs: CMDB.