CMDB instance API

Perform create, read, update, and delete operations on existing CMDB tables. Only one record can be inserted, updated, or deleted at a time.

These APIs require that the user have the ITIL role.

CMDB instance API - DELETE - /now/cmdb/instance/{classname}/{sys_id}/relation/{rel_sys_id}sys

Delete the relation for the specified CI.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}/{sys_id}/relation/{rel_sys_id}

Default URL: api/now/cmdb/instance/{className}/{sys_id}/relation/{rel_sys_id}

The path parameters.
  • className - The CMDB class name.
  • sys_id - The record sys_id.
  • rel_sys_id - The sys_id of the relation.

Supported request parameters

Table 1. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 2. Request headers
Header Description
None
Table 3. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 4. Status codes
Status code Description
None

CMDB instance API - GET -/now/cmdb/instance/{classname}

Query records for a CMDB class.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}

Default URL: api/now/cmdb/instance/{className}

The path parameter.
  • className - The CMDB class name.

Supported request parameters

Table 5. Parameters
Parameter Description
sysparm_query An encoded query string used to filter the results
sysparm_limit The maximum number of results to return per page. Default is 1000.
sysparm_offset A number of records to exclude from the query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 6. Request headers
Header Description
None
Table 7. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 8. Status codes
Status code Description
None

Response body

The API returns these JSON or XML elements in the response body.
{"result": [{
  "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
  "name": "PS LinuxApp01"},
  {
  "sys_id": "3a5dd3dbc0a8ce0100655f1ec66ed42c",
  "name": "PS LinuxApp02"}
  ]}

CMDB instance API - GET -/now/cmdb/instance/{classname}/{sys_id}

Query attributes and relationship information for a specific record.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}/{sys_id}

Default URL: api/now/cmdb/instance/{className}/{sys_id}

The path parameters.
  • className - The CMDB class name.
  • sys_id - The record sys_id.

Supported request parameters

Table 9. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
None
Table 11. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 12. Status codes
Status code Description
None

Response body

The API returns these JSON or XML elements in the response body.
{"result": {
  "attributes": {
    "cpu_manufacturer": {
      "link": "http://localhost:8080/api/now/table/core_company/7aad6d00c611228400f00e0f80b67d2d",
      "value": "7aad6d00c611228400f00e0f80b67d2d"  
  },
  "sys_updated_on": "2017-06-28 07:52:53",
  "ram": "2048",
  "skip_sync": "false",
  "sys_updated_by": "system",
  "sys_created_on": "2006-07-09 13:59:06",
  "sys_domain": {
    "link": "http://localhost:8080/api/now/table/sys_user_group/global",
    "value": "global"},
},
  "outbound_relations": [
   {"sys_id": "e7bac2d10a0a0aa700ba523f2a4ccf44",
   "type": {
     "link": "http://localhost:8080/api/now/table/cmdb_rel_type/e76b8c7b0a0a0aa70082c9f7c2f9dc64",
     "value": "e76b8c7b0a0a0aa70082c9f7c2f9dc64"},
   "target": {
     "link": "http://localhost:8080/api/now/cmdb/instance/cmdb_ci/e7a0a9be0a0a0aa7004bffbd1d177144",
     "value": "e7a0a9be0a0a0aa7004bffbd1d177144"}}],
  "inbound_relations": [
   {"sys_id": "5399a396c0a80164001b26484c2b22e5",
   "type": {
     "link": "http://localhost:8080/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
     "value": "1a9cb166f1571100a92eb60da2bce5c5"},
   "target": {
     "link": "http://localhost:8080/api/now/cmdb/instance/cmdb_ci/451047c6c0a8016400de0ae6df9b9d76",
     "value": "451047c6c0a8016400de0ae6df9b9d76"}},
   {"sys_id": "5f73c3ddc0a8010e003ca1aca98a6f07",
   "type":{
     "link": "http://localhost:8080/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",  
     "value": "1a9cb166f1571100a92eb60da2bce5c5"},
   "target": {
     "link": "http://localhost:8080/api/now/cmdb/instance/cmdb_ci/5f5c4854c0a8010e00c202b418f5b73b",
     "value": "5f5c4854c0a8010e00c202b418f5b73b"}},
   {"sys_id": "60bcdcebc0a8010e0124fb16964b989f",
   "type": {
     "link": "http://localhost:8080/api/now/table/cmdb_rel_type/60bc4e22c0a8010e01f074cbe6bd73c3",
     "value": "60bc4e22c0a8010e01f074cbe6bd73c3"},
   "target": {
     "link": "http://localhost:8080/api/now/cmdb/instance/cmdb_ci/5f8af237c0a8010e01a932999468b83a",
     "value": "5f8af237c0a8010e01a932999468b83a"}
}]}}

CMDB instance API - PATCH - /now/cmdb/instance/{classname}/{sys_id}

Replace the specified record with the message body. This API does not create/update/delete the associated relations.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}/{sys_id}

Default URL: api/now/cmdb/instance/{className}/{sys_id}

The path parameters.
  • className - The CMDB class name.
  • sys_id - The record sys_id.

Supported request parameters

Table 13. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 14. Request headers
Header Description
None
Table 15. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 16. Status codes
Status code Description
None

Request body

The API accepts these JSON or XML elements in the request body.
{“attributes”: {
  “field1”: “value1”,
  “field2”: “value2”},
  source: “ServiceNow” }

Response body

The API returns these JSON or XML elements in the response body.
{"result": [{
  "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
  "name": "PS LinuxApp01"},
  {
  "sys_id": "3a5dd3dbc0a8ce0100655f1ec66ed42c",
  "name": "PS LinuxApp02"}
  ]}

CMDB instance API - POST - /now/cmdb/instance/{classname}

Create a single CI with associated outbound and inbound relations. If the class has a dependent identification rule defined,then the input payload must contain the sys_id of the parent CI.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}

Default URL: api/now/v1/cmdb/instance/{className}

The path parameter.
  • className - The CMDB class name.

Supported request parameters

Table 17. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 18. Request headers
Header Description
None
Table 19. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 20. Status codes
Status code Description
None

Request body

The API accepts these JSON or XML elements in the request body.
{attributes: 
  {
     “field1”: “value1”,
     “field2”: “value2”},
“source”: “”
     “depends_on”:{ inbound_relation : {“target”:“sys_id”,“relation_type”: “relTypeSysId” }}
     “lookup”: [],
      inbound_relations: [
        {“rel_type” : “relTypeSysId”, “target”: “sysId1”},
        { “rel_type” : “relTypeSysId”, “target” : “sysId2” }],
      outbound_relations: [
        { “rel_type”: “relTypeSysId”, “target” : “sysId1”},
        { “rel_type” : “relTypeSysId”, “target”: “sysId2”}
  ]}

Response body

The API returns these JSON or XML elements in the response body.
{"result": [{
  "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
  "name": "PS LinuxApp01"},
  {
  "sys_id": "3a5dd3dbc0a8ce0100655f1ec66ed42c",
  "name": "PS LinuxApp02"}
  ]}

CMDB instance API - POST - /now/cmdb/instance/{classname}/{sys_id}/relation

Add a relation to the specified CI. The specified CI is the parent.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}/{sys_id}/relation

Default URL: api/now/cmdb/instance/{className}/{sys_id}/relation

The path parameters.
  • className - The CMDB class name.
  • sys_id - The record sys_id.

Supported request parameters

Table 21. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 22. Request headers
Header Description
None
Table 23. Response headers
Header Description
Location The location of the created resource.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 24. Status codes
Status code Description
None

Request body

The API accepts these JSON or XML elements in the request body.
  {“target_class” : “cmdb_ci_server”,
 “target_sys_id”: “sysId”,
 “rel_type”: “relTypeSysId”}

CMDB instance API - PUT - /now/cmdb/instance/{classname}/{sys_id}

Replace the specified record with the message body. This API does not create/update/delete the associated relations.

URL format

Versioned URL: api/now/v1/cmdb/instance/{className}/{sys_id}

Default URL: api/now/cmdb/instance/{className}/{sys_id}

The path parameters.
  • className - The CMDB class name.
  • sys_id - The record sys_id.

Supported request parameters

Table 25. Parameters
Parameter Description
sysparm_fields A comma-separated list of fields to return in the response
sysparm_relation_limit The maximum number of relations to return. Default is 1000.
sysparm_relation_offset A number of records to exclude from the relations query. Default is 0.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 26. Request headers
Header Description
None
Table 27. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 28. Status codes
Status code Description
None

Request body

The API accepts these JSON or XML elements in the request body.
{“attributes”: {
  “field1”: “value1”,
  “field2”: “value2”},
  source: “ServiceNow” }

Response body

The API returns these JSON or XML elements in the response body.
{"result": [{
  "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
  "name": "PS LinuxApp01"},
  {
  "sys_id": "3a5dd3dbc0a8ce0100655f1ec66ed42c",
  "name": "PS LinuxApp02"}
  ]}