The CMDB plugin's API

Configuration items are under /api/v1/x/cmdb/cis and their classes under /api/v1/x/cmdb/classes, 404 while the CMDB plugin is off; reading needs cmdb:read, changing cmdb:write. You see a CI when you can see one of its units and hold ci.read there. Its relationships are Service Configuration's (/api/v1/x/itsm/relationships, with itsm:read and itsm:write; the service catalogue API), with { kind: 'ci', id } as an end. Guide: configuration items.

Configuration items

Endpoint	What
GET ?orgId=&classId=&environmentId=&lifecycle=&health=&unitId=&owner=&teamId=&q=&identifier=&updated=&prop=&propValue=&gap=&exclude=&sort=&page=&pageSize=	CIs, a page at a time: { cis, total, page, pageSize } (pageSize up to 500). classId: the class or one below it. lifecycle: active (all but retired, the default), all or one of planned, live, retiring, retired. health: one or several (degraded,outage), or at_risk. unitId: the unit or one below it. owner: me, none or a person's id. q: the name, description or an identifier has it. identifier: an identifier's exact value, or kind:value (hostname:db-prod-01). gap: relationships (none either way), team (no support team) or expiring (an expires property within 30 days, or past). sort: name (the default), class or updated. Each row has class, classChain (its class and those above it), classPath, identifiers, health, atRiskVia, healthOverride, props and relationshipCount.
GET glance? (the same filters)	{ total, live, noOwner, mine, trouble, alone, noTeam, expiring } (trouble: degraded, outage or at risk; alone: no relationships; expiring: an expires property within 30 days or past).
GET options?orgId=	For the forms, in the organization (the first you see when left out): { orgId, orgs, units, environments }. 404 for an organization you can't see.
GET pick?orgId=&q=&serviceId=&ids=	For a picker on another plugin's record: at most 25 CIs of the organization you can see that aren't retired, by name or identifier (q); with serviceId and no q, the CIs joined to that service first; or named by id (ids, comma-separated). { items: [{ id, label, hint, health }] }.
GET people?unitIds=a,b&q=, GET teams?orgId=&q=	Who may own a CI with these units, and teams of the organization: at most 20 each.
POST	Add a CI (ci.write in one of its units): name, classId (a class of the organization, not archived), unitIds (one organization), optional lifecycle (default live), environmentId (one of Service Configuration's environments of the organization), ownerId (default: you, when you may own it; null: nobody), supportTeamId, description (Markdown), identifiers ([{ kind, source, value }]), links ([{ title, url }]), props (checked against the class and those above it).
GET <id>	The CI with description, links, version, relationships (both ways; an end you can't see is hidden, without its name), history (newest first: { version, kind, actor, at, changes: [{ field, from, to }] }), healthHistory and may: { edit, manage, status }.
GET <id>/as-of?at=	The record as it was at that moment (an ISO time in the past): { version, at, by, record } with the class, lifecycle, environment, owner, support team, units, identifiers, outgoing relationships, links and description as they were; 404 before it existed.
PATCH <id>	Change any field: unitIds and identifiers are the whole lists (units you can't see stay), classId (values of properties that no longer apply are kept, hidden), props. ci.write in one of its units, or being its owner. Each change that changes something raises version and adds a revision.
DELETE <id>	Delete a CI with no relationships that no case, incident, problem or change names, even closed ones (409 in_use, saying what: retire it instead); ci.settings.
PUT <id>/health	{ health, reason, hours }: set its health by hand (operational, maintenance, degraded, outage) for 1–168 hours (default 4); what relies on it is then at risk through it. ci.status, or being its owner. Answers the CI.
DELETE <id>/health	Back to the health its open incidents and changes give it.

Identifiers: kind is hostname, fqdn, ip, serial or external; source names the tool for external (required there, empty otherwise). Values are trimmed and kept in lower case. One that another CI of the organization has is refused with 409 identifier_taken.

Classes

Endpoint	What
GET ?orgId=&archived=1	An organization's classes (or those of every organization you see), in their order: { classes, may: { manage } }, each { id, orgId, parentId, name, description, icon, position, archived, used }. The starter set is added the first time. may.manage: ci.settings for the organization.
POST	{ orgId, name, description, icon, parentId } (ci.settings for the organization). Names are unique among siblings, whatever the case (409 name_taken); at most three levels (400 class_too_deep).
PATCH <id>	{ name, description, icon, parentId, position, archived }. A move below itself or one of its own is refused (400 class_loop).
DELETE <id>	A class no CI has, with nothing below it (409 class_in_use). It is taken off the data properties that also apply to other classes; a property only for it must be changed first (also 409 class_in_use).

icon is one of box, server, vm, container, network, balancer, domain, certificate, database, storage, queue, application, integration, cloud.

Data properties for CIs are the ci table of data properties, whose classIds are CI classes; a property applies to its classes and those below them.

Imports

Endpoint	What
POST imports	Import CIs of one class from CSV (ci.settings for the organization): { orgId, classId, csv, fileName, matchOn, dryRun }. matchOn: name (the default), hostname, fqdn, ip, serial or external:<tool>. dryRun is true unless set to false: then rows without errors are saved through the same checks as POST and PATCH, relationships are added after them, and the import is kept. Answers { dryRun, rows: [{ line, name, action, changes, errors }], created, updated, unchanged, refused, ignoredColumns, record }; action is create, update, unchanged or refused. At most 2,000 rows (400 too_many) and 5 MB.
GET imports?orgId=	The imports kept, newest first (200 at most): { id, at, actor, class, fileName, sha256, matchOn, rows, created, updated, unchanged, refused, refusals: [{ line, name, errors }] }. sha256 is of the CSV text as sent.

The columns are described in importing from a spreadsheet. The import is audited as cmdb.cis_imported; each CI it adds or changes sends its own cmdb.ci_created or cmdb.ci_changed.

Exports

Endpoint	What
GET export?orgId=&asOf=&scopeId=&format=	The CIs you can see as their records were at asOf (an ISO time; now when left out; 400 future for a time to come): format=csv (the default; a file, with X-Checksum-SHA256 and X-Export-Id) or json ({ columns, rows, record }, for the page to print). Columns: Name, Class, Lifecycle, Environment, Owner, Support team, Units, Identifiers, Relationships (from it), Version, Description. With scopeId (one of Service Configuration's audit scopes), only the CIs the services whose record named the scope then were joined to, downwards along every kind of relationship as it was then. Each export is kept and audited as cmdb.cis_exported.
GET exports?orgId=	The exports kept for the organization, newest first: { exports: [{ id, at, asOf, actor, scope, format, rows, sha256 }] }.

Owner reviews of CIs are Service Configuration's reviews of kind cmdb.ci (reviews): GET /api/v1/x/itsm/reviews?kind=cmdb.ci, and POST /api/v1/x/itsm/reviews with { kind: 'cmdb.ci', refId } (needs ci.settings) to start one now. The owner, or someone with ci.settings in one of its units, decides it.

Cases

With the CMDB on, a case names one CI, beside its service (/api/v1/x/cmdb/cases).

Endpoint	What
GET <ref>/ci	{ ci, hidden, setAt, serviceId, orgId, may: { change } }: its CI as you can see it (hidden: it names one you can't), the case's service (CIs joined to it come first in pick), and whether you may change it (case.write on the case).
PUT <ref>/ci	{ ciId }, or null to clear it: a CI you can see in the case's organization, not retired (400 unknown_ci or retired). Noted on the case's timeline (kind ci) and sent as cmdb.case_ci_changed. Answers as GET.

Incidents (ciId), problems and their known errors (ciIds) and changes (ciIds) name CIs in their own endpoints, with a ciId filter on their lists: see the incidents, problems and changes APIs.

Webhooks

cmdb.ci_created, cmdb.ci_changed, cmdb.ci_deleted, cmdb.ci_health_changed (with { from, to, cause }; cause is work (its open incidents or changes in progress), override, override_ended or chain) and cmdb.case_ci_changed ({ caseId, ref, ciId, name, previousCiId }). Relationships send Service Configuration's itsm.relationship_changed.

MCP tools

Scope	Tools
cmdb:read	ci_classes (an organization's classes as a tree, with how many CIs each has), ci_options (its units and environments), list_cis (by name, class, lifecycle, environment, owner and health; identifier finds one by host name, address or another identifier), get_ci (its record, identifiers, health and what it is at risk through, relationships both ways, data properties and latest history; as_of for the record then), ci_imports, export_cis (the CMDB on a date, all or an audit scope's; kept with its checksum), case_ci (a case's configuration item)
cmdb:write	create_ci (ci.write in one of its units; join it to services and other CIs with Service Configuration's add_relationship), update_ci (lists are replaced whole), set_ci_health (for some hours, with a reason; ci.status or owning it), import_cis (CSV text of one class; checks only unless dry_run is false; ci.settings), set_case_ci (case.write on the case)

Relationships and the Dependency map are Service Configuration's tools (relationship_types, dependency_map, add_relationship, remove_relationship, with itsm:read and itsm:write). Owner reviews of configuration items are service_reviews and decide_service_review.