Upsert Configuration Item Relationship

Submit a bulk operation to create or update one or more relationships between configuration items. 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 a configuration item relationship, you must have the following user permissions:

IT Service Configuration Item Type Manager
IT Service Configuration Item Owner

Request

JSON example

1mutation UpsertCIRelationship {
2  upsertCIRelationship(
3    input: {
4      payload: [
5        {
6          sourceCIId: 22
7          targetCIId: 33
8          relationshipType: "SD_NOVa"
9        }
10      ]
11    }
12  ) {
13    id
14    status
15    updatedAt
16    details
17    totalRecordCount
18    successRecordCount
19    failureRecordCount
20  }
21}

Properties

Name	Type	Description	Required or Optional	Available Version
`input`	UpsertCIRelationshipBulkInput	The top-level input container for the bulk create or update operation. Contains the array of configuration item relationship objects to process.	Required	66.0

UpsertCIRelationshipBulkInput

The top-level input container for create or update operations.

Name	Type	Description	Required or Optional	Available Version
`payload`	UpsertCIRelationshipInput	An array of configuration item relationship objects to be created or updated in a single bulk operation. Each element defines one relationship between a source and target configuration item.	Required	66.0

UpsertCIRelationshipInput

Defines the structure for a single configuration item relationship within a bulk upsert request.

Name	Type	Description	Required or Optional	Available Version
`sourceCIId`	String	The unique identifier of the source configuration item in the relationship.	Required	66.0
`targetCIId`	String	The unique identifier of the target configuration item in the relationship.	Required	66.0
`relationshipType`	String	The developer name of the configuration item relationship type. Use a valid relationship type developer name defined in your Configuration Management Database.	Required	66.0

Response

JSON example

1{
2  "data": {
3    "upsertCIRelationship": {
4      "id": 109,
5      "status": "Processing",
6      "updatedAt": "2025-11-14T10:15:00.123456Z",
7      "details": "Job queued - Upsert CI Relationship - 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 and completion status.	66.0
`status`	String	The initial status of the asynchronous job.	66.0
`updatedAt`	String	The date and time when the job was created or last updated, in YYYY-MM-DDTHH:MM:SSZ format.	66.0
`details`	String	User message describing the job.	66.0

After submitting the upsertCIRelationship mutation, use the returned job id with the getStatus query to check the operation progress and completion status.

Note