Upsert Configuration Items

Submit a bulk operation to create or update one or more configuration items (CIs). This is an asynchronous operation that returns a job ID, which you can use with the getStatus query to check the operation progress.

Special Access Rules

To upsert configuration items, you must have the following user permissions:

IT Service Configuration Item Type Manager
IT Service Configuration Item Owner

Request

JSON example

This example shows a sample request to upsert configuration items in bulk, including parent and relationship details.

1mutation UpsertCI {
2  upsertCI(
3    input: {
4      payload: [
5        {
6          cnfgItemType: "AWS Load Balancer"
7          ciTags: {
8            totalElements: 1
9            ciTags: [
10              {
11                type: "KEY_VALUE"
12                key: "searchtags"
13                keyId: 764952
14                valueId: 859952
15                value: "s1"
16              }
17            ]
18          }
19          parentCiId: "6780001"
20          relationshipType: "runs_on"
21          SD_AsNa: "LB-PROD-F5-01"
22          SD_St: "Active"
23          SD_IpAd: "10.0.2.10"
24        }
25      ]
26    }
27  ) {
28    id
29    status
30    updatedAt
31    details
32  }
33}

Properties

Name	Type	Description	Required or Optional	Available Version
`input`	UpsertCIBulkInput	A container object that holds the `payload` array containing one or more configuration item objects.	Required	66.0

UpsertCI Properties

Defines the structure for a single configuration item within the mutation payload.

Name	Type	Description	Required or Optional	Available Version
`ciTags`	CiTags	The tags associated with the configuration item.	Required	67.0
`cnfgItemType`	String	The type of configuration item.	Required	66.0
`parentCiId`	String	The ID of the parent configuration item for which a component configuration item is created.	Optional	66.0
`relationshipType`	String	Developer name of the CI Relationship.	Optional	66.0

CiTags Properties

Defines the structure for the configuration item type tags within the mutation payload.

Field	Type	Description	Available Version
`key`	BigInteger	The tag key or name.	67.0
`keyId`	BigInteger	The unique identifier of the tag key.	67.0
`type`	String	The tag type: `KEY_VALUE` (key-value pair) or `KEY_ONLY` (key only).	67.0
`value`	String	The tag value. This field is null for `KEY_ONLY` tags.	67.0
`valueId`	String	The unique identifier of the tag value. This field is null for `KEY_ONLY` tags.	67.0

Response

JSON example

This example is a sample response from the upsertCI mutation.

1{
2  "data": {
3    "upsertCI": {
4      "id": 108,
5      "status": "Processing",
6      "updatedAt": "2025-11-14T10:15:00.123456Z",
7      "details": "Job queued - Upsert CI - Canonical API (1 items)"
8    }
9  }
10}

Properties

Name	Type	Description	Available Version
`id`	Integer	The unique identifier of the asynchronous job. Use this ID with the `getStatus` query to check the operation progress.	66.0
`status`	String	The initial status of the asynchronous job.	66.0
`updatedAt`	String	The date and time when the job was created, in YYYY-MM-DDTHH:MM:SSZ format.	66.0
`details`	String	A message indicating the job has been queued and is being processed.	66.0

After submitting the upsertCI mutation, use the returned job id with the getStatus query to check the operation progress and completion status.
When using the upsertCI operation, you can request any available attribute to be included in the response. The attributes you can include:
- Standard Attributes: Many attributes are available out-of-the-box.
- Custom Attributes: You can create and include custom attributes using the sObject API.
Add any attribute using its Developer Name (for example, SD_AsNa—Asset Name) to specify exactly which information you want to receive for your Configuration Items (CIs).

Note