🗺️ REST API: Network Mapper

The complete usage guide for the Network Mapper module of the REST API — diagrams, nodes, connectors, version snapshots and the suggestions feed. 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 Network Mapper:

🤖 Built for discovery agents	The target consumer is an agentic network-discovery tool keeping diagrams alive: read what's drawn, ask what's missing, add the new switch, snapshot a version first. Stale network diagrams are the classic ITSM failure — this API is the fix.
🧠 Diagrams a machine can understand	Nodes aren't anonymous boxes — each is bound to a CMDB object, and reads hydrate everything: the CI's name, class, effective icon, planned flag, optionally its full typed properties, plus each connector's endpoint objects and the CMDB relationship verb it represents, and a layout block with the canvas bounding box.
🔧 Surgical edits with stable ids	The editor can only save the whole canvas (regenerating every node id). The API adds incremental operations — add/move/restyle/remove a single node or connector — and the ids stay stable, so an agent can track elements across edits.
🧲 Think in CIs, not node ids	Connectors accept from_object_id/to_object_id, and cmdb_relationship_id: "auto" binds the drawn line to the real CMDB relationship between the two objects. Omitted x/y coordinates auto-place in a tidy column for a human to arrange later.
🕰️ Versions as undo points	The module's linear version chain: only the newest (leaf) version is editable, history is frozen. POST .../versions snapshots before automated changes — a free rollback point for cautious agents.

---

🚀 Quick start — the discovery-agent loop

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

# What's on the diagram? (full hydration: CIs, classes, verbs, layout)
curl -s "$B/network-diagrams/7?include_properties=true" -H "$K"

# What's missing? CMDB neighbours of drawn objects, not yet on the canvas
curl -s "$B/network-diagrams/7/suggestions" -H "$K"

# Snapshot first (free undo), then draw the newly discovered switch
NEW=$(curl -s -X POST "$B/network-diagrams/7/versions" -H "$K" \
  -H "Content-Type: application/json" -d '{"version_label": "auto-sync"}' | jq -r '.data.id')
curl -s -X POST "$B/network-diagrams/$NEW/nodes" -H "$K" -H "Content-Type: application/json" \
  -d '{"cmdb_object_id": 41}'          # x/y omitted — auto-placed
curl -s -X POST "$B/network-diagrams/$NEW/connectors" -H "$K" -H "Content-Type: application/json" \
  -d '{"from_object_id": 41, "to_object_id": 38, "cmdb_relationship_id": "auto"}'

---

🗺️ Diagrams

🟢 GET /network-diagrams   🔑 network_diagrams.read

Current versions only by default (all_versions=true for frozen history), most recently updated first, with node/connector counts. Filters: q (titles + descriptions), contains_object_id (every diagram a given CI is drawn on — "which maps show this server?"), created_by, updated_since, pagination.

🔵 POST /network-diagrams   🔑 network_diagrams.create

title required. Optionally ship the whole initial drawing in one call:

{ "title": "Head office network",
  "nodes": [ { "cmdb_object_id": 1, "ref": "fw" },
             { "cmdb_object_id": 2, "ref": "sw1", "x": 300, "y": 100, "size": "large" } ],
  "connectors": [ { "from_ref": "fw", "to_ref": "sw1", "cmdb_relationship_id": "auto" } ] }

Nodes may carry a ref (any string) for connectors to reference; nodes without x/y are auto-placed. Also settable: paper_size/paper_orientation (A4/A3/A2/Letter/Tabloid), branding header/footer slots (null = inherit the org default).

🟢 GET /network-diagrams/{id}   🔑 network_diagrams.read

The full machine-legible drawing. Add ?include_properties=true for each object's typed CI property values:

{ "data": { "id": 7, "title": "Head office network", "is_current": true,
    "nodes": [ { "id": 224, "x": 100, "y": 100, "size": "medium", "size_px": 56,
                 "icon": "server", "icon_override": null,
                 "object": { "id": 16, "name": "SQLSVR01", "is_planned": false,
                             "class": { "id": 12, "name": "Server", "icon": "server" } } } ],
    "connectors": [ { "id": 185,
        "from": { "node_id": 224, "object_id": 16, "object_name": "SQLSVR01" },
        "to":   { "node_id": 225, "object_id": 38, "object_name": "CORE-SW01" },
        "relationship": { "id": 21, "verb": "connects to", "inverse_verb": "is connected from" },
        "label": null, "line_style": "dashed" } ],
    "layout": { "bounds": { "min_x": 100, "min_y": 100, "max_x": 316, "max_y": 156 },
                "width": 216, "height": 56,
                "node_sizes_px": { "small": 40, "medium": 56, "large": 80 } } } }

🟠 PATCH /network-diagrams/{id}   🔑 network_diagrams.update

Partial metadata update (title, description, version_label, paper, branding). Sending nodes and/or connectors switches to full contents replace — both sets are replaced and every node id regenerates, exactly like an editor save. For surgical edits, use the node/connector endpoints instead. A frozen historical version is a 409.

🔴 DELETE /network-diagrams/{id}   🔑 network_diagrams.delete

Leaf-only: deleting the current version resurfaces its parent as current ("discard this draft"). A version with newer history after it is a 409 — the UI lets that corrupt the chain; the API refuses. ?chain=true deletes the entire version chain, transactionally.

---

🕰️ Versions

🟢 GET /network-diagrams/{id}/versions   🔑 network_diagrams.read

The whole chain containing this diagram, oldest first, with is_current flags.

🔵 POST /network-diagrams/{id}/versions   🔑 network_diagrams.create

Clones the current version forward — nodes, connectors, paper and branding all copied; the clone becomes editable and the source freezes (the editor's "New version"). title/description/version_label default to the source's. 409 unless called on the current version.

---

🧲 Suggestions

🟢 GET /network-diagrams/{id}/suggestions   🔑 network_diagrams.read

CMDB neighbours of on-diagram objects that aren't drawn yet — found via relationships in both directions and object_ref property links (one direction more than the module's own related-objects feed). Each suggestion carries everything needed to draw it:

{ "data": [ { "object": { "id": 39, "name": "CORE-RTR01", "is_planned": false,
                "class": { "id": 18, "name": "Network Device", "icon": "network" } },
              "via": [ { "kind": "relationship", "from_object_id": 38,
                         "label": "connects to", "relationship_id": 26 } ] } ] }

?object_id= scopes to one on-diagram object's neighbours; ?limit= caps results (default 50). An empty array means the diagram already shows everything the CMDB knows about.

---

🔧 Nodes & connectors (incremental, stable ids)

All these require the current version (frozen history is a 409) and carry 🔑 network_diagrams.update.

🔵 POST /network-diagrams/{id}/nodes

One node (body = the node) or a batch ({"nodes": [...]}). cmdb_object_id required; x/y optional (auto-placed in a fresh column right of the drawing); size small|medium|large; icon_override any key from GET /cmdb-icons. An object already on the diagram is a 409 unless allow_duplicate: true.

🟠 PATCH /network-diagrams/{id}/nodes/{node_id}   /   🔴 DELETE .../nodes/{node_id}

PATCH moves/restyles (x, y, size, icon_override — null reverts to the class icon). DELETE removes the node and every connector touching it (count returned).

🔵 POST /network-diagrams/{id}/connectors

Endpoints by from_node_id/to_node_id or from_object_id/to_object_id (422 if the object isn't on the diagram, or is on it twice — disambiguate with node ids). cmdb_relationship_id: an id, null, or "auto" (binds to the existing CMDB relationship between the two objects, either direction). Self-loops are a 422; an already-connected pair is a 409 unless allow_duplicate: true. label free text, line_style solid|dashed.

🟠 PATCH .../connectors/{connector_id}   /   🔴 DELETE .../connectors/{connector_id}

PATCH updates label, line_style, cmdb_relationship_id (null clears, "auto" re-resolves).

---

📚 Reference

🟢 GET /cmdb-icons   🔑 reference.read

The icon catalogue — every icon_key usable as a class icon or a node's icon_override.

---

📌 Notes & gotchas

• Everything is a CI. You can't draw a free-form box — nodes must reference CMDB objects. If discovery finds something new, create the CI first (via the CMDB API), then draw it. That constraint is the feature: the diagram is always backed by real inventory.
• Strict where the editor is lenient: unknown object ids, sizes, icon keys and line styles are 422s (the editor silently skips bad rows on save).
• Deleting a CMDB object removes it from every diagram — nodes and their connectors go with the CI (as of the #705 integrity fix; previously grown installs silently dropped the boxes from view while leaving orphaned rows behind).
• The PNG/PDF export is client-side (rendered in the browser), so the API can't produce images — only the structure. Render pipelines can consume the hydrated GET instead.
• Coordinates are canvas pixels, top-left origin; layout.node_sizes_px gives each size class's footprint so an agent can reason about overlap and spacing.

---

See also: REST API (how it all works) · REST API: CMDB (the objects behind the nodes) · Network Mapper (the module itself) · the other module guides linked from the sidebar.