The CMDB Instance API provides endpoints to create, read, update, and delete operations on existing Configuration Management Database (CMDB) tables. You can only insert, update, or delete one record at a time.

This API requires the user have the ITIL role.

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

Deletes the relation for the specified configuration item (CI).

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
rel_sys_id Sys_id of the relation to remove.

Data type: String
sys_id Sys_id of the CI.

Data type: String
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
Name Description
None

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 4. Request headers
Header Description
None
Table 5. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Name Description
None

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server/0f4ac6c4b750230096c3e4f6ee11a9fe/relation/b0dbda5347c12200e0ef563dbb9a718f" \
--request DELETE \
--user 'username':'password'

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

Returns the available configuration items (CI) for a specified Configuration Management Database (CMDB) class (table).

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 7. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
Table 8. Query parameters
Name Description
sysparm_limit Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first.

Note: Unusually large sysparm_limit values can impact system performance.

Data type: Number

Default: 20

Maximum: 100
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Don't pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
sysparm_query Encoded query used to filter the result set. You can use a UI filter to obtain a properly encoded query.
Syntax: sysparm_query=<col_name><operator><value>.
  • <col_name>: Name of the table column to filter against.
  • <operator>: Supports the following values:
    • =: Exactly matches <value>.
    • !=: Does not match <value>.
    • ^: Logically AND multiple query statements.
    • ^OR: Logically OR multiple query statements.
    • LIKE: <col_name> contains the specified string. Only works for <col_name> fields whose data type is string.
    • STARTSWITH: <col_name> starts with the specified string. Only works for <col_name> fields whose data type is string.
    • ENDSWITH: <col_name> ends with the specified string. Only works for <col_name> fields whose data type is string.
    <value>: Value to match against.

All parameters are case-sensitive. Queries can contain more than one entry, such as sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>].

For example:

(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

Encoded queries also support order by functionality. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query.

Syntax:
  • ORDERBY<col_name>
  • ORDERBYDESC<col_name>

For example: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

This query filters all active records and orders the results in ascending order by number, and then in descending order by category.

If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query.
Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs.

Data type: String
Table 9. Request body parameters (XML or JSON)
Name Description
None

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
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
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 API HTTP response codes.

Response body parameters (JSON or XML)

Name Description
name Name of a CI within the specified class.

Data type: String
sys_id Sys_id of the CI.

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

"result": [
  {
    "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
    "name": "PS LinuxApp01"
  },
  {
    "sys_id": "3a5dd3dbc0a8ce0100655f1ec66ed42c",
    "name": "PS LinuxApp02"
  }
]

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

Returns attributes and relationship information for a specified configuration item (CI) record.

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 13. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
sys_id Sys_id of the CI record to retrieve.

Data type: String
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
Name Description
None

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 16. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 17. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Table 19. Response parameters
NameDescription
attributes Data attributes currently in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

Data type: Object
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
inbound_relations List of objects that define the inbound relations associated with the CI.

Data type: Array

"inbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
inbound_relations.sys_id Sys_id of the inbound CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
inbound_relations.target Information that describes the target inbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.target.display_value Name of the inbound relation to display in a user interface.

Data type: String
inbound_relations.target.link CMDB REST endpoint URL to use to retrieve the inbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.target.value Sys_id of the inbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.type Information about the type of inbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.type.display_value Name of the inbound type to display in a user interface.

Data type: String
inbound_relations.type.link Table REST endpoint URL to use to retrieve the inbound relation type from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
inbound_relations.type.value Sys_id of the type of inbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations List of objects that define the outbound relations associated with the CI.

Data type: Array

"outbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
outbound_relations.sys_id Sys_id of the outbount CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
outbound_relations.target Required. Information about the target outbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.target.display_value Name of the outbound relation to display in a user interface.

Data type: String
outbound_relations.target.link CMDB REST endpoint URL to use to retrieve the outbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.target.value Sys_id of the outbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.type Information about the type of outbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.type.display_value Name of the outbound type to display in a user interface.

Data type: String
outbound_relations.type.link Table REST endpoint URL to use to retrieve the outbound relation from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations.type.value Sys_id of the type of outbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server/70bc4e11c0a8210d01f074cbe6bd73b4" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "outbound_relations": [
      {
        "sys_id": "3a62e64ac0a8ce0100aead1e3fd5439f",
        "type": {
          "display_value": "Depends on::Used by",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
          "value": "1a9cb166f1571100a92eb60da2bce5c5"
        },
        "target": {
          "display_value": "PS ORA01",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
          "value": "3a307c930a0a0bb400353965d0b8861f"
        }
      },
      {
        "sys_id": "3a67513fc0a8ce0100914a76cea11b02",
        "type": {
          "display_value": "Exchanges data with::Exchanges data with",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/607ad1b2c0a8010e01941856b365af90",
          "value": "607ad1b2c0a8010e01941856b365af90"
        },
        "target": {
          "display_value": "PS ORA01",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
          "value": "3a307c930a0a0bb400353965d0b8861f"
        }
      }
    ],
    "attributes": {
      "firewall_status": "Intranet",
      "os_address_width": "",
      "attested_date": "",
      "operational_status": "1",
      "os_service_pack": "",
      "cpu_core_thread": "",
      "cpu_manufacturer": "",
      "sys_updated_on": "2020-07-08 11:16:51",
      "discovery_source": "",
      "first_discovered": "",
      "due_in": "",
      "used_for": "Production",
      "invoice_number": "",
      "gl_account": "",
      "sys_created_by": "glide.maint",
      "warranty_expiration": "",
      "ram": "2048",
      "cpu_name": "",
      "cpu_speed": "2800",
      "owned_by": "",
      "checked_out": "",
      "kernel_release": "",
      "sys_domain_path": "/",
      "classification": "Production",
      "disk_space": "40",
      "object_id": "",
      "maintenance_schedule": "",
      "cost_center": "",
      "attested_by": "",
      "dns_domain": "",
      "assigned": "2020-01-04 07:00:00",
      "purchase_date": "",
      "life_cycle_stage": "",
      "short_description": "",
      "cd_speed": "",
      "floppy": "",
      "managed_by": {
        "display_value": "Lynda Caraway",
        "link": "https://instance.service-now.com/api/now/table/sys_user/8a826bf03710200044e0bfc8bcbe5d72",
        "value": "8a826bf03710200044e0bfc8bcbe5d72"
      },
      "os_domain": "",
      "last_discovered": "",
      "can_print": "false",
      "sys_class_name": "cmdb_ci_linux_server",
      "manufacturer": {
        "display_value": "Iris",
        "link": "https://instance.servicenow.com/api/now/table/core_company/c115c2f737e3100044e0bfc8bcbe5d46",
        "value": "c115c2f737e3100044e0bfc8bcbe5d46"
      },
      "cpu_count": "1",
      "vendor": {
        "display_value": "Cloudward Inc",
        "link": "https://instance.servicenow.com/api/now/table/core_company/3efe8c4c37423000158bbfc8bcbe5d7d",
        "value": "3efe8c4c37423000158bbfc8bcbe5d7d"
      },
      "life_cycle_stage_status": "",
      "model_number": "",
      "assigned_to": "",
      "start_date": "",
      "os_version": "2.6.9-22.0.1.ELsmp",
      "serial_number": "",
      "cd_rom": "false",
      "support_group": "",
      "unverified": "false",
      "correlation_id": "",
      "attributes": "",
      "asset": {
        "display_value": "P1000091 - Iris 5875",
        "link": "https://instance.servicenow.com/api/now/table/alm_asset/0bc1ba8837f3100044e0bfc8bcbe5dbb",
        "value": "0bc1ba8837f3100044e0bfc8bcbe5dbb"
      },
      "form_factor": "",
      "cpu_core_count": "",
      "skip_sync": "false",
      "attestation_score": "",
      "sys_updated_by": "system",
      "sys_created_on": "2008-10-26 17:17:28",
      "sys_domain": {
        "display_value": "global",
        "link": "https://instance.servicenow.com/api/now/table/sys_user_group/global",
        "value": "global"
      },
      "cpu_type": "Intel",
      "install_date": "2019-08-18 08:00:00",
      "asset_tag": "P1000091",
      "dr_backup": "",
      "hardware_substatus": "",
      "fqdn": "",
      "change_control": "",
      "internet_facing": "false",
      "delivery_date": "",
      "hardware_status": "",
      "install_status": "1",
      "supported_by": "",
      "name": "PS LinuxApp01",
      "subcategory": "",
      "default_gateway": "",
      "chassis_type": "",
      "virtual": "false",
      "assignment_group": "",
      "managed_by_group": "",
      "sys_id": "3a290cc60a0a0bb400000bdb386af1cf",
      "po_number": "",
      "checked_in": "",
      "sys_class_path": "/!!/!2/!(/!!/!0",
      "mac_address": "",
      "company": {
        "display_value": "ACME Corporation",
        "link": "https://instance.servicenow.com/api/now/table/core_company/e7c1f3d53790200044e0bfc8bcbe5deb",
        "value": "e7c1f3d53790200044e0bfc8bcbe5deb"
      },
      "justification": "",
      "department": "",
      "cost": "45557.5",
      "comments": "",
      "os": "Linux Red Hat",
      "sys_mod_count": "24",
      "monitor": "false",
      "model_id": {
        "display_value": "Iris 5875",
        "link": "https://instance.servicenow.com/api/now/table/cmdb_model/5f5fbcc3c0a8010e00f3b27814f3b96b",
        "value": "5f5fbcc3c0a8010e00f3b27814f3b96b"
      },
      "ip_address": "",
      "duplicate_of": "",
      "sys_tags": "",
      "cost_cc": "USD",
      "order_date": "",
      "schedule": "",
      "environment": "",
      "due": "",
      "attested": "false",
      "location": {
        "display_value": "322 West 52nd Street, New York,NY",
        "link": "https://instance.servicenow.com/api/now/table/cmn_location/25ab9f690a0a0bb3001c5fec1d0d7bcb",
        "value": "25ab9f690a0a0bb3001c5fec1d0d7bcb"
      },
      "category": "Do not migrate to asset",
      "fault_count": "0",
      "host_name": "",
      "lease_id": ""
    },
    "inbound_relations": [
      {
        "sys_id": "3a5e4d8ac0a8ce010005145afb730818",
        "type": {
          "display_value": "Depends on::Used by",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
          "value": "1a9cb166f1571100a92eb60da2bce5c5"
        },
        "target": {
          "display_value": "PS Apache01",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a27d4370a0a0bb4006316812bf45439",
          "value": "3a27d4370a0a0bb4006316812bf45439"
        }
      },
      {
        "sys_id": "3a5e4d9cc0a8ce010097f2f5c2f65fd8",
        "type": {
          "display_value": "Depends on::Used by",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
          "value": "1a9cb166f1571100a92eb60da2bce5c5"
        },
        "target": {
          "display_value": "PS Apache02",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a27f1520a0a0bb400ecd6ff7afcf036",
          "value": "3a27f1520a0a0bb400ecd6ff7afcf036"
        }
      },
      {
        "sys_id": "3a5e4d9fc0a8ce0100a3754fac26fe56",
        "type": {
          "display_value": "Depends on::Used by",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
          "value": "1a9cb166f1571100a92eb60da2bce5c5"
        },
        "target": {
          "display_value": "PS Apache03",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a2810c20a0a0bb400268337d6e942ca",
          "value": "3a2810c20a0a0bb400268337d6e942ca"
        }
      }
    ]
  }
}

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

Creates a single configuration item (CI) with the specified outbound and inbound relations within the specified Configuration Management Database (CMDB) table.

Note: If the CMDB class has a dependent identification rule defined, then the input payload must contain the sys_id of an existing CI. For example, for outbound_relations, the target parameter must contain the sys_id of an existing CI, which then becomes the child. For inbound_relations, it becomes the parent.

  "depends_on": {
    "outbound_relations":
      {
        "target": "b4fd7c8437201000deeabfc8bcbe5dc1",
        "type": "60bc4e22c0a8010e01f074cbe6bd73c3"
      }
    }

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 20. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
Table 21. Query parameters
Name Description
None

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 23. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 24. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Table 26. Response parameters
NameDescription
attributes Data attributes currently in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

Data type: Object
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
inbound_relations List of objects that define the inbound relations associated with the CI.

Data type: Array

"inbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
inbound_relations.sys_id Sys_id of the inbound CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
inbound_relations.target Information that describes the target inbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.target.display_value Name of the inbound relation to display in a user interface.

Data type: String
inbound_relations.target.link CMDB REST endpoint URL to use to retrieve the inbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.target.value Sys_id of the inbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.type Information about the type of inbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.type.display_value Name of the inbound type to display in a user interface.

Data type: String
inbound_relations.type.link Table REST endpoint URL to use to retrieve the inbound relation type from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
inbound_relations.type.value Sys_id of the type of inbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations List of objects that define the outbound relations associated with the CI.

Data type: Array

"outbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
outbound_relations.sys_id Sys_id of the outbount CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
outbound_relations.target Required. Information about the target outbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.target.display_value Name of the outbound relation to display in a user interface.

Data type: String
outbound_relations.target.link CMDB REST endpoint URL to use to retrieve the outbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.target.value Sys_id of the outbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.type Information about the type of outbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.type.display_value Name of the outbound type to display in a user interface.

Data type: String
outbound_relations.type.link Table REST endpoint URL to use to retrieve the outbound relation from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations.type.value Sys_id of the type of outbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Example: cURL Request

The following code example shows how to call this endpoint.

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password" \
--data {
  "outbound_relations": [
    {
      "type" : "1a9cb166f1571100a92eb60da2bce5c5",
      "target" : "3a307c930a0a0bb400353965d0b8861f"
    },
    {
      "type" : "607ad1b2c0a8010e01941856b365af90",
      "target" : "3a307c930a0a0bb400353965d0b8861f"
    }
  ],
  "attributes": {
    "name" : "lnux999",
    "firewall_status": "Intranet"
  },
  "source": "ServiceNow",
  "inbound_relations": [
    {
      "type" : "1a9cb166f1571100a92eb60da2bce5c5",
      "target" : "3a27d4370a0a0bb4006316812bf45439"
    }
  ]
}
{
    "result": {
        "outbound_relations": [
            {
                "sys_id": "403ff2641b425010593876a61a4bcb4b",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            },
            {
                "sys_id": "443ff2641b425010593876a61a4bcb4c",
                "type": {
                    "display_value": "Exchanges data with::Exchanges data with",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/607ad1b2c0a8010e01941856b365af90",
                    "value": "607ad1b2c0a8010e01941856b365af90"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            }
        ],
        "attributes": {
            "firewall_status": "Intranet",
            "os_address_width": "",
            "attested_date": "",
            "operational_status": "1",
            "os_service_pack": "",
            "cpu_core_thread": "",
            "cpu_manufacturer": "",
            "sys_updated_on": "2020-07-13 20:27:28",
            "discovery_source": "ServiceNow",
            "first_discovered": "2020-07-13 20:27:28",
            "due_in": "",
            "used_for": "Production",
            "invoice_number": "",
            "gl_account": "",
            "sys_created_by": "dora.gray",
            "warranty_expiration": "",
            "ram": "",
            "cpu_name": "",
            "cpu_speed": "",
            "owned_by": "",
            "checked_out": "",
            "kernel_release": "",
            "sys_domain_path": "/",
            "classification": "Production",
            "disk_space": "",
            "object_id": "",
            "maintenance_schedule": "",
            "cost_center": "",
            "attested_by": "",
            "dns_domain": "",
            "assigned": "",
            "purchase_date": "",
            "life_cycle_stage": "",
            "short_description": "",
            "cd_speed": "",
            "floppy": "",
            "managed_by": "",
            "os_domain": "",
            "last_discovered": "2020-07-13 20:27:28",
            "can_print": "false",
            "sys_class_name": "cmdb_ci_linux_server",
            "manufacturer": "",
            "cpu_count": "",
            "vendor": "",
            "life_cycle_stage_status": "",
            "model_number": "",
            "assigned_to": "",
            "start_date": "",
            "os_version": "",
            "serial_number": "",
            "cd_rom": "false",
            "support_group": "",
            "unverified": "false",
            "correlation_id": "",
            "attributes": "",
            "asset": "",
            "form_factor": "",
            "cpu_core_count": "",
            "skip_sync": "false",
            "attestation_score": "",
            "sys_updated_by": "dora.gray",
            "sys_created_on": "2020-07-13 20:27:28",
            "sys_domain": {
                "display_value": "global",
                "link": "https://instance.servicenow.com/api/now/table/sys_user_group/global",
                "value": "global"
            },
            "cpu_type": "",
            "install_date": "",
            "asset_tag": "",
            "dr_backup": "",
            "hardware_substatus": "",
            "fqdn": "",
            "change_control": "",
            "internet_facing": "true",
            "delivery_date": "",
            "hardware_status": "installed",
            "install_status": "1",
            "supported_by": "",
            "name": "lnux299",
            "subcategory": "Computer",
            "default_gateway": "",
            "chassis_type": "",
            "virtual": "false",
            "assignment_group": "",
            "managed_by_group": "",
            "sys_id": "0c3ff2641b425010593876a61a4bcb39",
            "po_number": "",
            "checked_in": "",
            "sys_class_path": "/!!/!2/!(/!!/!0",
            "mac_address": "",
            "company": "",
            "justification": "",
            "department": "",
            "cost": "",
            "comments": "",
            "os": "",
            "sys_mod_count": "0",
            "monitor": "false",
            "model_id": "",
            "ip_address": "",
            "duplicate_of": "",
            "sys_tags": "",
            "cost_cc": "USD",
            "order_date": "",
            "schedule": "",
            "environment": "",
            "due": "",
            "attested": "false",
            "location": "",
            "category": "Hardware",
            "fault_count": "0",
            "host_name": "",
            "lease_id": ""
        },
        "inbound_relations": [
            {
                "sys_id": "c03ff2641b425010593876a61a4bcb49",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS Apache01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a27d4370a0a0bb4006316812bf45439",
                    "value": "3a27d4370a0a0bb4006316812bf45439"
                }
            }
        ]
    }
}

Example: cURL Request

The following code example shows how to call this endpoint for a class that has a dependant identification rule defined. The outbound_relations.target must be included in the payload and contain the sys_id of an existing CI.

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password" \
--data {
  "attributes": {
    "name": "test",
    "sys_class_name":"cmdb_ci_db_mssql_instance",
    "instance_name":"Iname"
  },
  "source": "ServiceNow",
  "depends_on": {
    "outbound_relations":
      {
        "target": "b4fd7c8437201000deeabfc8bcbe5dc1",
        "type": "60bc4e22c0a8010e01f074cbe6bd73c3"
      }
    }
  }
}
{
  "result": {
    "outbound_relations": [
      {
        "sys_id": "505cfa3a53662110af64ddeeff7b1217",
        "type": {
          "display_value": "Runs on::Runs",
          "link": http://instance.servicenow.com/api/now/table/cmdb_rel_type/60bc4e22c0a8010e01f074cbe6bd73c3,
          "value": "60bc4e22c0a8010e01f074cbe6bd73c3"
        },
        "target": {
          "display_value": "*ANNIE-IBM",
          "link": http://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/b4fd7c8437201000deeabfc8bcbe5dc1,
          "value": "b4fd7c8437201000deeabfc8bcbe5dc1"
        }
      }
    ],
    "attributes": {
      "attested_date": "",
      "operational_status": "1",
      "running_process_command": "",
      "sys_updated_on": "2023-05-05 21:28:24",
      "type": "",
      "running_process_key_parameters": "",
      "rp_command_hash": "",
      "discovery_source": "ServiceNow",
      "first_discovered": "2023-05-05 21:28:24",
      "due_in": "",
      "service_pack": "",
      "used_for": "Production",
      "is_clustered": "false",
      "invoice_number": "",
      "gl_account": "",
      "sys_created_by": "admin",
      "warranty_expiration": "",
      "owned_by": "",
      "checked_out": "",
      "rp_key_parameters_hash": "",
      "sys_domain_path": "/",
      "business_unit": "",
      "version": "",
      "cpu_sockets": "",
      "maintenance_schedule": "",
      "cost_center": "",
      "attested_by": "",
      "dns_domain": "",
      "assigned": "",
      "purchase_date": "",
      "life_cycle_stage": "",
      "short_description": "",
      "managed_by": "",
      "port_dynamic": "false",
      "last_discovered": "2023-05-05 21:28:24",
      "can_print": "false",
      "sys_class_name": "cmdb_ci_db_mssql_instance",
      "manufacturer": "",
      "cl_port": "",
      "vendor": "",
      "life_cycle_stage_status": "",
      "model_number": "",
      "config_file": "",
      "assigned_to": "",
      "start_date": "",
      "instance_name": "Iname",
      "serial_number": "",
      "engine_edition": "",
      "support_group": "",
      "version_name": "",
      "unverified": "false",
      "correlation_id": "",
      "attributes": "",
      "asset": "",
      "config_directory": "",
      "tcp_port": "",
      "listener_name": "",
      "skip_sync": "false",
      "pid": "",
      "attestation_score": "",
      "sys_updated_by": "admin",
      "install_directory": "",
      "sys_created_on": "2023-05-05 21:28:24",
      "sys_domain": {
        "display_value": "global",
        "link": http://instance.servicenow.com/api/now/table/sys_user_group/global,
        "value": "global"
      },
      "install_date": "",
      "asset_tag": "",
      "fqdn": "",
      "change_control": "",
      "delivery_date": "",
      "install_status": "1",
      "supported_by": "",
      "name": "test",
      "subcategory": "Database",
      "assignment_group": "",
      "edition": "",
      "managed_by_group": "",
      "sys_id": "185cba3a53662110af64ddeeff7b12af",
      "po_number": "",
      "database": "",
      "checked_in": "",
      "sys_class_path": "/!!/!(/!2/!,",
      "mac_address": "",
      "company": "",
      "justification": "",
      "department": "",
      "cost": "",
      "comments": "",
      "attestation_status": "Not Yet Reviewed",
      "sys_mod_count": "0",
      "monitor": "false",
      "model_id": "",
      "ip_address": "",
      "duplicate_of": "",
      "sys_tags": "",
      "cost_cc": "USD",
      "order_date": "",
      "schedule": "",
      "environment": "",
      "due": "",
      "attested": "false",
      "location": "",
      "category": "Resource",
      "fault_count": "0",
      "lease_id": ""
    },
    "inbound_relations": []
  }
}

Example: cURL Request

The following code example shows what is returned when a sys_id is not passed for a class that has a dependant identification rule defined. Same result occurs if the sys_id is invalid.

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password" \
--data "{
  "attributes": {
    "name": "test",
    "sys_class_name":"cmdb_ci_db_mssql_instance",
    "instance_name":"Iname"
  },
  "source": "ServiceNow",
  "depends_on": {
    "outbound_relations": {
        "type": "60bc4e22c0a8010e01f074cbe6bd73c3"
    }
  }
}
{
  "error": {
    "detail": "Exception while executing request: null Check logs for error trace or enable glide.rest.debug property to verify REST request processing",
    "message": "Exception while executing request: null"
  },
  "status": "failure"
}

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

Updates the specified configuration item (CI) record with the specified attribute name-value pairs. This endpoint does not create, update, or delete the associated relations.

Note: This endpoint does not conform to the HTML specifications. Standard PUT endpoints are destructive in that they remove any elements that are not included in the request. This endpoint does not remove non-specified elements.

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 27. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
sys_id Sys_id of the CI record to update.

Data type: String
Table 28. Query parameters
Name Description
None
Table 29. Request body parameters (XML or JSON)
Name Description
attributes Data attributes to replace in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

For information about attestation, see CIs attestation.

Data type: Object
source Required. Entity that updated the information. This must be one of the choice values specified in the discovery_source field in the Configuration Item [cmdb_ci] table.

Data type: String

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 30. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 31. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Table 33. Response parameters
NameDescription
attributes Data attributes currently in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

Data type: Object
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
inbound_relations List of objects that define the inbound relations associated with the CI.

Data type: Array

"inbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
inbound_relations.sys_id Sys_id of the inbound CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
inbound_relations.target Information that describes the target inbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.target.display_value Name of the inbound relation to display in a user interface.

Data type: String
inbound_relations.target.link CMDB REST endpoint URL to use to retrieve the inbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.target.value Sys_id of the inbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.type Information about the type of inbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.type.display_value Name of the inbound type to display in a user interface.

Data type: String
inbound_relations.type.link Table REST endpoint URL to use to retrieve the inbound relation type from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
inbound_relations.type.value Sys_id of the type of inbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations List of objects that define the outbound relations associated with the CI.

Data type: Array

"outbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
outbound_relations.sys_id Sys_id of the outbount CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
outbound_relations.target Required. Information about the target outbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.target.display_value Name of the outbound relation to display in a user interface.

Data type: String
outbound_relations.target.link CMDB REST endpoint URL to use to retrieve the outbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.target.value Sys_id of the outbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.type Information about the type of outbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.type.display_value Name of the outbound type to display in a user interface.

Data type: String
outbound_relations.type.link Table REST endpoint URL to use to retrieve the outbound relation from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations.type.value Sys_id of the type of outbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server/70bc4e11c0a8210d01f074cbe6bd73b4" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password" \
--data {
  "attributes": {
    "firewall_status": "Extranet",
    "discovery_source": "ServiceNows",
    "name": "Linux299",
    "used_for": "Pre-production",
    "container": "Box"
  },
  "source": "ServiceNow"
}

{
    "result": {
        "outbound_relations": [
            {
                "sys_id": "403ff2641b425010593876a61a4bcb4b",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.service-now.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.service-now.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            },
            {
                "sys_id": "443ff2641b425010593876a61a4bcb4c",
                "type": {
                    "display_value": "Exchanges data with::Exchanges data with",
                    "link": "https://instance.service-now.com/api/now/table/cmdb_rel_type/607ad1b2c0a8010e01941856b365af90",
                    "value": "607ad1b2c0a8010e01941856b365af90"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.service-now.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            }
        ],
        "attributes": {
            "firewall_status": "Extranet",
            "os_address_width": "",
            "attested_date": "",
            "operational_status": "1",
            "os_service_pack": "",
            "cpu_core_thread": "",
            "cpu_manufacturer": "",
            "sys_updated_on": "2020-07-13 20:59:40",
            "discovery_source": "ServiceNow",
            "first_discovered": "2020-07-13 20:27:28",
            "due_in": "",
            "used_for": "Pre-production",
            "invoice_number": "",
            "gl_account": "",
            "sys_created_by": "dora.gray",
            "warranty_expiration": "",
            "ram": "",
            "cpu_name": "",
            "cpu_speed": "",
            "owned_by": "",
            "checked_out": "",
            "kernel_release": "",
            "sys_domain_path": "/",
            "classification": "Production",
            "disk_space": "",
            "object_id": "",
            "maintenance_schedule": "",
            "cost_center": "",
            "attested_by": "",
            "dns_domain": "",
            "assigned": "",
            "purchase_date": "",
            "life_cycle_stage": "",
            "short_description": "",
            "cd_speed": "",
            "floppy": "",
            "managed_by": "",
            "os_domain": "",
            "last_discovered": "2020-07-13 20:59:40",
            "can_print": "false",
            "sys_class_name": "cmdb_ci_linux_server",
            "manufacturer": "",
            "cpu_count": "",
            "vendor": "",
            "life_cycle_stage_status": "",
            "model_number": "",
            "assigned_to": "",
            "start_date": "",
            "os_version": "",
            "serial_number": "",
            "cd_rom": "false",
            "support_group": "",
            "unverified": "false",
            "correlation_id": "",
            "attributes": "",
            "asset": {
                "display_value": "Unknown",
                "link": "https://instance.service-now.com/api/now/table/alm_asset/21cfba641b425010593876a61a4bcb52",
                "value": "21cfba641b425010593876a61a4bcb52"
            },
            "form_factor": "",
            "cpu_core_count": "",
            "skip_sync": "false",
            "attestation_score": "",
            "sys_updated_by": "dora.gray",
            "sys_created_on": "2020-07-13 20:27:28",
            "sys_domain": {
                "display_value": "global",
                "link": "https://instance.service-now.com/api/now/table/sys_user_group/global",
                "value": "global"
            },
            "cpu_type": "",
            "install_date": "",
            "asset_tag": "",
            "dr_backup": "",
            "hardware_substatus": "",
            "fqdn": "",
            "change_control": "",
            "internet_facing": "true",
            "delivery_date": "",
            "hardware_status": "installed",
            "install_status": "1",
            "supported_by": "",
            "name": "Linux299",
            "subcategory": "Computer",
            "default_gateway": "",
            "chassis_type": "",
            "virtual": "false",
            "assignment_group": "",
            "managed_by_group": "",
            "sys_id": "0c3ff2641b425010593876a61a4bcb39",
            "po_number": "",
            "checked_in": "",
            "sys_class_path": "/!!/!2/!(/!!/!0",
            "mac_address": "",
            "company": "",
            "justification": "",
            "department": "",
            "cost": "",
            "comments": "",
            "os": "",
            "sys_mod_count": "3",
            "monitor": "false",
            "model_id": {
                "display_value": "Unknown",
                "link": "https://instance.service-now.com/api/now/table/cmdb_model/0ce0a2681b4e1010593876a61a4bcba6",
                "value": "0ce0a2681b4e1010593876a61a4bcba6"
            },
            "ip_address": "",
            "duplicate_of": "",
            "sys_tags": "",
            "cost_cc": "USD",
            "order_date": "",
            "schedule": "",
            "environment": "",
            "due": "",
            "attested": "false",
            "location": "",
            "category": "Hardware",
            "fault_count": "0",
            "host_name": "",
            "lease_id": ""
        },
        "inbound_relations": [
            {
                "sys_id": "c03ff2641b425010593876a61a4bcb49",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.service-now.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS Apache01",
                    "link": "https://instance.service-now.com/api/now/cmdb/instance/cmdb_ci/3a27d4370a0a0bb4006316812bf45439",
                    "value": "3a27d4370a0a0bb4006316812bf45439"
                }
            }
        ]
    }
}

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

Adds an inbound and/or outbound relation to the specified configuration item (CI). The specified CI is the parent.

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 34. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
sys_id Sys_id of the CI record to update.

Data type: String
Table 35. Query parameters
Name Description
None

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 37. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 38. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Table 40. Response parameters
NameDescription
attributes Data attributes currently in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

Data type: Object
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
inbound_relations List of objects that define the inbound relations associated with the CI.

Data type: Array

"inbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
inbound_relations.sys_id Sys_id of the inbound CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
inbound_relations.target Information that describes the target inbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.target.display_value Name of the inbound relation to display in a user interface.

Data type: String
inbound_relations.target.link CMDB REST endpoint URL to use to retrieve the inbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.target.value Sys_id of the inbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.type Information about the type of inbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.type.display_value Name of the inbound type to display in a user interface.

Data type: String
inbound_relations.type.link Table REST endpoint URL to use to retrieve the inbound relation type from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
inbound_relations.type.value Sys_id of the type of inbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations List of objects that define the outbound relations associated with the CI.

Data type: Array

"outbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
outbound_relations.sys_id Sys_id of the outbount CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
outbound_relations.target Required. Information about the target outbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.target.display_value Name of the outbound relation to display in a user interface.

Data type: String
outbound_relations.target.link CMDB REST endpoint URL to use to retrieve the outbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.target.value Sys_id of the outbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.type Information about the type of outbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.type.display_value Name of the outbound type to display in a user interface.

Data type: String
outbound_relations.type.link Table REST endpoint URL to use to retrieve the outbound relation from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations.type.value Sys_id of the type of outbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci_linux_server/3a290cc60a0a0bb400000bdb386af1cf/relation" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password" \
--data {
  "outbound_relations": [
    {
      "type" : "1a9cb166f1571100a92eb60da2bce5c5",
      "target" : "3a307c930a0a0bb400353965d0b8861f"
    },
    {
      "type" : "607ad1b2c0a8010e01941856b365af90",
      "target" : "3a307c930a0a0bb400353965d0b8861f"
    }
  ],
  "source": "ServiceNow",
  "inbound_relations": [
    {
      "type" : "1a9cb166f1571100a92eb60da2bce5c5",
      "target" : "3a27d4370a0a0bb4006316812bf45439"
    }
  ]
}
{
    "result": {
        "outbound_relations": [
            {
                "sys_id": "403ff2641b425010593876a61a4bcb4b",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            },
            {
                "sys_id": "443ff2641b425010593876a61a4bcb4c",
                "type": {
                    "display_value": "Exchanges data with::Exchanges data with",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/607ad1b2c0a8010e01941856b365af90",
                    "value": "607ad1b2c0a8010e01941856b365af90"
                },
                "target": {
                    "display_value": "PS ORA01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
                    "value": "3a307c930a0a0bb400353965d0b8861f"
                }
            }
        ],
        "attributes": {
            "firewall_status": "Active",
            "os_address_width": "",
            "attested_date": "",
            "operational_status": "1",
            "os_service_pack": "",
            "cpu_core_thread": "",
            "cpu_manufacturer": "",
            "sys_updated_on": "2020-07-13 21:24:05",
            "discovery_source": "ServiceNow",
            "first_discovered": "2020-07-13 20:27:28",
            "due_in": "",
            "used_for": "Production",
            "invoice_number": "",
            "gl_account": "",
            "sys_created_by": "dora.gray",
            "warranty_expiration": "",
            "ram": "",
            "cpu_name": "",
            "cpu_speed": "",
            "owned_by": "",
            "checked_out": "",
            "kernel_release": "",
            "sys_domain_path": "/",
            "classification": "Production",
            "disk_space": "",
            "object_id": "",
            "maintenance_schedule": "",
            "cost_center": "",
            "attested_by": "",
            "dns_domain": "",
            "assigned": "",
            "purchase_date": "",
            "life_cycle_stage": "",
            "short_description": "",
            "cd_speed": "",
            "floppy": "",
            "managed_by": "",
            "os_domain": "",
            "last_discovered": "2020-07-13 21:24:05",
            "can_print": "false",
            "sys_class_name": "cmdb_ci_linux_server",
            "manufacturer": "",
            "cpu_count": "",
            "vendor": "",
            "life_cycle_stage_status": "",
            "model_number": "",
            "assigned_to": "",
            "start_date": "",
            "os_version": "",
            "serial_number": "",
            "cd_rom": "false",
            "support_group": "",
            "unverified": "false",
            "correlation_id": "",
            "attributes": "",
            "asset": {
                "display_value": "Unknown",
                "link": "https://instance.servicenow.com/api/now/table/alm_asset/21cfba641b425010593876a61a4bcb52",
                "value": "21cfba641b425010593876a61a4bcb52"
            },
            "form_factor": "",
            "cpu_core_count": "",
            "skip_sync": "false",
            "attestation_score": "",
            "sys_updated_by": "dora.gray",
            "sys_created_on": "2020-07-13 20:27:28",
            "sys_domain": {
                "display_value": "global",
                "link": "https://instance.servicenow.com/api/now/table/sys_user_group/global",
                "value": "global"
            },
            "cpu_type": "",
            "install_date": "",
            "asset_tag": "",
            "dr_backup": "",
            "hardware_substatus": "",
            "fqdn": "",
            "change_control": "",
            "internet_facing": "true",
            "delivery_date": "",
            "hardware_status": "installed",
            "install_status": "1",
            "supported_by": "",
            "name": "Linux299",
            "subcategory": "Computer",
            "default_gateway": "",
            "chassis_type": "",
            "virtual": "false",
            "assignment_group": "",
            "managed_by_group": "",
            "sys_id": "0c3ff2641b425010593876a61a4bcb39",
            "po_number": "",
            "checked_in": "",
            "sys_class_path": "/!!/!2/!(/!!/!0",
            "mac_address": "",
            "company": "",
            "justification": "",
            "department": "",
            "cost": "",
            "comments": "",
            "os": "",
            "sys_mod_count": "4",
            "monitor": "false",
            "model_id": {
                "display_value": "Unknown",
                "link": "https://instance.servicenow.com/api/now/table/cmdb_model/0ce0a2681b4e1010593876a61a4bcba6",
                "value": "0ce0a2681b4e1010593876a61a4bcba6"
            },
            "ip_address": "",
            "duplicate_of": "",
            "sys_tags": "",
            "cost_cc": "USD",
            "order_date": "",
            "schedule": "",
            "environment": "",
            "due": "",
            "attested": "false",
            "location": "",
            "category": "Hardware",
            "fault_count": "0",
            "host_name": "",
            "lease_id": ""
        },
        "inbound_relations": [
            {
                "sys_id": "c03ff2641b425010593876a61a4bcb49",
                "type": {
                    "display_value": "Depends on::Used by",
                    "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
                    "value": "1a9cb166f1571100a92eb60da2bce5c5"
                },
                "target": {
                    "display_value": "PS Apache01",
                    "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a27d4370a0a0bb4006316812bf45439",
                    "value": "3a27d4370a0a0bb4006316812bf45439"
                }
            }
        ]
    }
}

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

Replaces the attributes in the specified configuration item (CI) record with the specified name-value pairs. This endpoint does not create, update, or delete the associated relations.

URL format

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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 41. Path parameters
Name Description
className CMDB class name. This is the name of the table that contains the desired CI records, such as cmdb_ci_linux_server or cmdb_ci_apache_web_server.

Data type: String
sys_id Sys_id of the CI record to update.

Data type: String
Table 42. Query parameters
Name Description
None
Table 43. Request body parameters (XML or JSON)
Name Description
attributes Data attributes to replace in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

For information about attestation, see CIs attestation.

Data type: Object
source Required. Entity that updated the information. This must be one of the choice values specified in the discovery_source field in the Configuration Item [cmdb_ci] table.

Data type: String

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 44. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 45. 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 API HTTP response codes.

Response body parameters (JSON or XML)

Table 47. Response parameters
NameDescription
attributes Data attributes currently in the CI record. The available attributes depend on the specified CMDB class. You can locate the available attributes in the associated CMDB table which typically begins with "cmdb_ci", such as cmdb_ci_linux_server or cmdb_ci_mfp_printer.

Data type: Object
error Information on any errors encountered while processing the endpoint request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail Additional information about the error.

Data type: String
error.message Message that identifies the error.

Data type: String
inbound_relations List of objects that define the inbound relations associated with the CI.

Data type: Array

"inbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
inbound_relations.sys_id Sys_id of the inbound CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
inbound_relations.target Information that describes the target inbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.target.display_value Name of the inbound relation to display in a user interface.

Data type: String
inbound_relations.target.link CMDB REST endpoint URL to use to retrieve the inbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.target.value Sys_id of the inbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
inbound_relations.type Information about the type of inbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
inbound_relations.type.display_value Name of the inbound type to display in a user interface.

Data type: String
inbound_relations.type.link Table REST endpoint URL to use to retrieve the inbound relation type from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
inbound_relations.type.value Sys_id of the type of inbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations List of objects that define the outbound relations associated with the CI.

Data type: Array

"outbound_relations": [
  {
    "sys_id": "String",
    "target": {Object},
    "type": {Object}
  }
]
outbound_relations.sys_id Sys_id of the outbount CI relationship. Located in the CI Relationship [cmdb_rel_ci] table.

Data type: String
outbound_relations.target Required. Information about the target outbound relation.

Data type: Object

"target": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.target.display_value Name of the outbound relation to display in a user interface.

Data type: String
outbound_relations.target.link CMDB REST endpoint URL to use to retrieve the outbound relation from the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.target.value Sys_id of the outbound CI. Located in the Configuration Item [cmdb_ci] table.

Data type: String
outbound_relations.type Information about the type of outbound relationship.

Data type: Object

"type": {
  "display_value": "String",
  "link": "String",
  "value": "String"
}
outbound_relations.type.display_value Name of the outbound type to display in a user interface.

Data type: String
outbound_relations.type.link Table REST endpoint URL to use to retrieve the outbound relation from the CI Relationship Type [cmdb_rel_type] table.

Data type: String
outbound_relations.type.value Sys_id of the type of outbound relationship. Located in the CI Relationship Type [cmdb_rel_type] table.

Data type: String
status Only appears if an error is encountered. Status of the endpoint processing.

Possible value: failure

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_class_sw/70bc4e11c0a8210d01f074cbe6bd73b4" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json"\
--user "username":"password"\
--data {
    "attributes": {
      "firewall_status": "Active",
      "name": "Linux299",
      "used_for": "Production"
    },
    "source": "ServiceNow"
}
{
  "result": {
    "outbound_relations": [
      {
        "sys_id": "403ff2641b425010593876a61a4bcb4b",
        "type": {
          "display_value": "Depends on::Used by",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
          "value": "1a9cb166f1571100a92eb60da2bce5c5"
        },
        "target": {
          "display_value": "PS ORA01",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
          "value": "3a307c930a0a0bb400353965d0b8861f"
        }
      },
      {
        "sys_id": "443ff2641b425010593876a61a4bcb4c",
        "type": {
          "display_value": "Exchanges data with::Exchanges data with",
          "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/607ad1b2c0a8010e01941856b365af90",
          "value": "607ad1b2c0a8010e01941856b365af90"
        },
        "target": {
          "display_value": "PS ORA01",
          "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a307c930a0a0bb400353965d0b8861f",
          "value": "3a307c930a0a0bb400353965d0b8861f"
        }
      }
    ],
    "attributes": {
      "firewall_status": "Active",
      "os_address_width": "",
      "attested_date": "",
      "operational_status": "1",
      "os_service_pack": "",
      "cpu_core_thread": "",
      "cpu_manufacturer": "",
      "sys_updated_on": "2020-07-13 21:24:05",
      "discovery_source": "ServiceNow",
      "first_discovered": "2020-07-13 20:27:28",
      "due_in": "",
      "used_for": "Production",
      "invoice_number": "",
      "gl_account": "",
      "sys_created_by": "dora.gray",
      "warranty_expiration": "",
      "ram": "",
      "cpu_name": "",
      "cpu_speed": "",
      "owned_by": "",
      "checked_out": "",
      "kernel_release": "",
      "sys_domain_path": "/",
      "classification": "Production",
      "disk_space": "",
      "object_id": "",
      "maintenance_schedule": "",
      "cost_center": "",
      "attested_by": "",
      "dns_domain": "",
      "assigned": "",
      "purchase_date": "",
      "life_cycle_stage": "",
      "short_description": "",
      "cd_speed": "",
      "floppy": "",
      "managed_by": "",
      "os_domain": "",
      "last_discovered": "2020-07-13 21:24:05",
      "can_print": "false",
      "sys_class_name": "cmdb_ci_linux_server",
      "manufacturer": "",
      "cpu_count": "",
      "vendor": "",
      "life_cycle_stage_status": "",
      "model_number": "",
      "assigned_to": "",
      "start_date": "",
      "os_version": "",
      "serial_number": "",
      "cd_rom": "false",
      "support_group": "",
      "unverified": "false",
      "correlation_id": "",
      "attributes": "",
      "asset": {
        "display_value": "Unknown",
        "link": "https://instance.servicenow.com/api/now/table/alm_asset/21cfba641b425010593876a61a4bcb52",
        "value": "21cfba641b425010593876a61a4bcb52"
      },
      "form_factor": "",
      "cpu_core_count": "",
      "skip_sync": "false",
      "attestation_score": "",
      "sys_updated_by": "dora.gray",
      "sys_created_on": "2020-07-13 20:27:28",
      "sys_domain": {
        "display_value": "global",
        "link": "https://instance.servicenow.com/api/now/table/sys_user_group/global",
        "value": "global"
      },
      "cpu_type": "",
      "install_date": "",
      "asset_tag": "",
      "dr_backup": "",
      "hardware_substatus": "",
      "fqdn": "",
      "change_control": "",
      "internet_facing": "true",
      "delivery_date": "",
      "hardware_status": "installed",
      "install_status": "1",
      "supported_by": "",
      "name": "Linux299",
      "subcategory": "Computer",
      "default_gateway": "",
      "chassis_type": "",
      "virtual": "false",
      "assignment_group": "",
      "managed_by_group": "",
      "sys_id": "0c3ff2641b425010593876a61a4bcb39",
      "po_number": "",
      "checked_in": "",
      "sys_class_path": "/!!/!2/!(/!!/!0",
      "mac_address": "",
      "company": "",
      "justification": "",
      "department": "",
      "cost": "",
      "comments": "",
      "os": "",
      "sys_mod_count": "4",
      "monitor": "false",
      "model_id": {
        "display_value": "Unknown",
        "link": "https://instance.servicenow.com/api/now/table/cmdb_model/0ce0a2681b4e1010593876a61a4bcba6",
        "value": "0ce0a2681b4e1010593876a61a4bcba6"
      },
      "ip_address": "",
      "duplicate_of": "",
      "sys_tags": "",
      "cost_cc": "USD",
      "order_date": "",
      "schedule": "",
      "environment": "",
      "due": "",
      "attested": "false",
      "location": "",
      "category": "Hardware",
      "fault_count": "0",
      "host_name": "",
      "lease_id": ""
    },
    "inbound_relations": [
      {
        "sys_id": "c03ff2641b425010593876a61a4bcb49",
         "type": {
           "display_value": "Depends on::Used by",
            "link": "https://instance.servicenow.com/api/now/table/cmdb_rel_type/1a9cb166f1571100a92eb60da2bce5c5",
            "value": "1a9cb166f1571100a92eb60da2bce5c5"
          },
          "target": {
            "display_value": "PS Apache01",
            "link": "https://instance.servicenow.com/api/now/cmdb/instance/cmdb_ci/3a27d4370a0a0bb4006316812bf45439",
            "value": "3a27d4370a0a0bb4006316812bf45439"
          }
        }
      ]
    }
}