Docs

# CMDB and Service Model API

Warning

Additional authorization is required to fulfill any request.

Use in the request the header Authorization: Bearer <Personal Token>.

Where can I get a personal token?

# Get available types of CI

GET /api/public/sm/v2/rsm/config-item-types

The query returns a list of CI type models.

# Response codes

Code Description
200 The request was successfully completed.
401 Failed to authorize the user.
500 An unexpected error occurred while processing your request.

# Get available CMDB systems

GET /api/public/sm/v2/rsm/cmdb-systems

The query returns a list of CMDB system models.

# Response codes

Code Description
200 The request was successfully completed.
401 Failed to authorize the user.
500 An unexpected error occurred while processing your request.

# Get available workgroups

GET /api/public/sm/v2/rsm/work-groups

The query returns a list of workgroup models.

# Response codes

Code Description
200 The request was successfully completed.
401 Failed to authorize the user.
500 An unexpected error occurred while processing your request.

# Get all available CI

GET /api/public/sm/v2/rsm/config-items

The request returns a list of CIs with a minimum set of attributes: id and name.

# Response codes

Code Description
200 The request was successfully completed.
401 Failed to authorize the user.
500 An unexpected error occurred while processing your request.

# Get CI by filter

POST /api/public/sm/v2/rsm/config-items/filter

# Query body

{
	"ids": [1, 2, 3],
	"names": ["Sample CI 1", "Sample CI 2"],
	"labels": {
		"single_label": "value",
		"multi_label": ["value_a", "value_b"],
		"label_with_any_value": null
	}
}

# Request body fields

Field name Field type Description
ids number[] or null List of CI ids. If null, then any.
names string[] or null List of CI names. If null, then any.
labels object or null Dictionary of CI labels. If null, then any.

All specified labels must be present in the required CIs. If one or more values are specified for a label, then the searched CIs must contain at least one of the values for this label. If the value of the label in the filter is null, filtering is performed only by the name of the label.

Upon successful execution of the query, a list of CIs that match the filter conditions is returned with a minimum set of attributes: the identifier id, the namename, and the dictionary of labels labels.

# Response codes

Code Description
200 The request was successfully completed.
401 Failed to authorize the user.
500 An unexpected error occurred while processing your request.

# Create CI

POST /api/public/sm/v2/rsm/config-items

The query returns the model of the created CI.

# Query body

{
  "id": 0,
  "name": "Name",
  "description": "Description",
  "parent": {
    "id": 0
  },
  "configItemType": {
    "id": 0
  },
  "ownerWorkGroup": {
    "id": 0
  },
  "labels": {
     "label_a_name": "label_value",
     "label_b_name": ["label_value_1", "label_value_2"],
     "label_c_name": null

  },
  "cmdbSystemId": -1,
  "sharedToWorkGroups": [{
    "workGroupId": 0,
    "shareType": "ConfigItem",
    "grants": ["base-system.rsm.read"]
  }]
}

# Request body fields

Field name Field type Description
id number null CI identifier. If null, it will be generated automatically.
name string CI name.
description string CI description.
parent { id: number } / null The identifier of the parent CI, with which you want to establish a link when creating a CI. If specify null or 0, the CI will be created as the root element.
configItemType { id: number } / null CI type. If null, the default type will be assigned.
ownerWorkGroup { id: number } / null Workgroup, the owner of CI. If the identifier of the parent CI is specified, then the owner WG will be set the same as for this CI.
labels object / null Dictionary of CI labels
cmdbSystemId number The identifier for the instance of the external CMDB system. Value -1 for default CMDB.
sharedToWorkGroups object[] List of access rights models for specific workgroups.

# Response codes

Code Description
201 CI successful created.
400 Empty body query.
400 Invalid data model in the request body.
400 It is required to set the name of the CI.
400 CI is required to specify it owner workgroup.
400 Invalid CI identifier value.
400 Invalid workgroup ID value.
400 CI with {id} already exist in DB.
400 The parent CI with the identifier {id} does not exist in the DB.
400 CI with name {name} already exist with type {typeName}.
400 CI type with id {id} not found in userspace.
401 Failed to authorize user.
403 Not have permission to add CI to workgroup.
404 Workgroup with id {id} not found.
415 Invalid input data type. Specify data type: application/json.
500 An unexpected error occurred while processing the request.

# Delete CI

DELETE /api/public/sm/v2/rsm/config-items/{id}?applyGrants=false

{id} – CI identifier.

# Request parameters

Parameter Type Description
applyGrants boolean If specify true – apply access rights to subordinated CIs. Default – false.

# Response codes

Code Description
204 CI successful deleted.
400 Invalid CI identifier value.
401 Failed to authorize the user.
403 Not have permission to remove the CI.
404 CI with identifier {id} not found.
500 An unexpected error occurred while processing the request.

# Changing general information of CI

PUT /api/public/sm/v2/rsm/config-items/{id}

{id} – CI identifier.

Query returns the model of the updated CI.

# Query body

{
  "name": "Name",
  "description": "Description",
  "configItemType": {
    "id": 0
  },
  "ownerWorkGroup": {
    "id": 0
  },
  "labels": {
     "label_a_name": "label_value",
     "label_b_name": ["label_value_1", "label_value_2"],
     "label_c_name": null
     },
  "cmdbSystemId": -1
}

# Request body fields

Field name Field type
name string CI name.
description string CI description.
configItemType { id: number } / null CI type. If null, the default type will be assigned.
ownerWorkGroup { id: number } / null Workgroup owner of CI
labels object / null Dictionary of CI labels
cmdbSystemId number The identifier for the instance of the external CMDB system. Value -1 for default CMDB.

# Response codes

Codes Description
200 The request was successfully completed.
400 Body query is empty.
400 Invalid data model in the request body.
400 It is required to set the name of the CI.
400 CI is required to specify it owner workgroup.
400 Invalid CI identifier value.
400 Invalid workgroup ID value.
400 CI with name {name} already exist with type {typeName}.
400 CI type with id {id} not found in userspace.
401 Failed to authorize the user.
403 Insufficient privileges to update the CI.
404 CI with identifier {id} not found.
404 Workgroup with identifier {id} not found.
500 An unexpected error occurred while processing the request.

# Grant access to CI

POST /api/public/sm/v2/rsm/config-items/{id}/work-groups

{id} – CI identifier.

The request returns the model of the updated CI.

# Query body

{
  "workGroupId": 0,
  "shareType": "ConfigItem",
  "grants": ["base-system.rsm.basic-read"]
}

# Query body fields

Field name Field type Description
workGroupId number Workgroup identifier. 0 – all working groups, including future ones.
shareType string Grant type.
grants string[] Granted rights.

# Response codes

Codes Description
200 The request was successfully completed.
400 Body query is empty.
400 Invalid data model in the request body.
400 You want to specify a list of rights granted.
400 Invalid CI identifier value.
400 Invalid workgroup ID value.
400 The access rule has already been set.
401 Failed to authorize the user.
403 Insufficient privileges to update the CI.
404 CI with identifier {id} not found.
404 Workgroup with identifier {id} not found.
500 An unexpected error occurred while processing the request.

# Update access to CI

PUT /api/public/sm/v2/rsm/config-items/{id}/work-groups

{id} – CI identifier.

The request returns the model of the updated CI.

# Query body

{
  "id": 0,
  "shareType": "ConfigItem",
  "grants": ["base-system.rsm.basic-read"]
}

# Query body fields

Field name Field type Description
id number CI identifier.
shareType string Type of rights.
grants string[] Rights granted.

# Response codes

Codes Description
200 The request was successfully completed.
400 Body query is empty.
400 Invalid data model in the request body.
400 Requires a workgroup ID.
400 You want to specify a list of rights granted.
400 Invalid CI identifier value.
400 Invalid value for the model ID of the access to the CI.
401 Failed to authorize the user.
403 Insufficient privileges to update the CI.
404 CI with identifier {id} not found.
404 The model for granting access to the CI with the ID {id} was not found.
500 An unexpected error occurred while processing the request.

# Remove granted access to CI

DELETE /api/public/sm/v2/rsm/config-items/{id}/work-groups/{sharedId}

{id} – CI identifier
{sharedId} – the identifier of the model for granting access to CIs.

The request returns the model of the updated CI.

# Response codes

Code Description
204 The request was successfully completed.
400 Invalid CI identifier value.
400 Invalid value for the model identifier of the access to CI.
401 Failed to authorize the user.
403 Insufficient privileges to update the CI.
404 CI with identifier {id} not found.
404 The model for granting access to the CI with the ID {id} was not found.
500 An unexpected error occurred while processing the request.

# Get information about CI

GET /api/public/sm/v2/rsm/config-items/{id}?includeState=false&includeHealth=false

{id} – CI identifier

The request returns the CI model.

# Query parameters

Parameter name Parameter type Parameter description
includeState boolean If specify true – include information about status of CI. Default – false.
includeHealth boolean If specify true – include information about health of CI. Default – false.

# Response codes

Code Description
200 The request was successfully completed.
400 Invalid CI identifier value.
401 Failed to authorize the user.
403 There are no rights to view CI.
404 CI with identifier {id} not found.
500 An unexpected error occurred while processing the request.

POST /api/public/sm/v2/rsm/config-items/{parentId}/children

{parentId} – Parent CI identifier.

The query returns the subordinated CI model.

# Query body

The request body contains the identifier of the subordinated CI.

{
  "id": 0
}

# Response codes

Code Description
200 The request was successfully completed.
400 Body query is empty.
400 Invalid data model in body of query.
400 Invalid CI identifier value.
400 Cannot establish subordination links between CI belonging to different workgroups.
401 Failed to authorize the user.
403 Insufficient privileges to update the parent CI.
404 Parent CI with identifier {id} not found.
404 Child CI with identifier {id} not found.
415 Invalid input data type. Specify data type: application/json.
500 An unexpected error occurred while processing the request.

POST /api/public/sm/v2/rsm/config-items/{dependentId}/influentials

{dependentId} – identifier of the CI being impacted.

The request returns an updated list of CIs impacting the dependent CI with a minimum set of attributes: identifier {id} and name {name}.

# Query body

The request body contains the identifier of the impacting CI.

{
  "id": 0
}

# Response codes

Codes Description
200 The request was successfully completed.
400 Body query is empty.
400 Invalid data model in body of query.
400 Invalid CI identifier value.
401 Failed to authorize the user.
403 Insufficient privileges to update the dependent CI.
403 Insufficient privileges to update the influencing CI.
404 Dependent CI with identifier {id} not found.
404 Influencing CI with identifier {id} not found.
415 Invalid input data type. Specify data type: application/json.
500 An unexpected error occurred while processing the request.

DELETE /api/public/sm/v2/rsm/config-items/{parentId}/children/{childId}

{parentId} – Parent CI identifier
{childId} – Child CI identifier.

The request returns model of the previously subordinated CI.

# Response codes

Code Description
200 The request was successfully completed.
400 Invalid CI identifier value.
401 Failed to authorize the user.
403 Insufficient privileges to update the parent CI.
404 Parent CI with identifier {id} not found.
404 Child CI with identifier {id} not found.
500 An unexpected error occurred while processing the request.

DELETE /api/public/sm/v2/rsm/config-items/{dependentId}/influentials/{influentialId}

{dependentId} – Dependent CI identifier,
{influentialId} – Influent CI identifier.

The request returns an updated list of CIs influencing the dependent CI with a minimum set of attributes: identifier {id} and name {name}.

# Response codes

Code Description
200 The request was successfully completed.
400 Invalid CI identifier value.
401 Failed to authorize the user.
403 Insufficient privileges to update the dependent CI.
403 Insufficient privileges to update the influencing CI.
404 Dependent CI with identifier {id} not found.
404 Child CI with identifier {id} not found.
500 An unexpected error occurred while processing the request.

# Appendix

# CI type model

{
  "id": 0,
  "name": "Name",
  "description": "Description"
}

# CMDB system model

{
  "id": 0,
  "name": "Name"
}

# Workgroup model

{
  "id": 0,
  "name": "Name"
}

# CI model

{
  "id": 0,
  "name": "Name",
  "description": "Description",
  "parent": {
    "id": 0
    "name": "Name"
  },
  "ownerWorkGroup": {
    "id": 0,
    "name": "Name"
  },
  "configItemType": {
    "id": 0,
    "name": "Name",
    "description": "Description",
  },
  "labels": {
     "label_a_name": "label_value",
     "label_b_name": ["label_value_1", "label_value_2"],
     "label_c_name": null
  },
  "entityInfo": {
    "createdAt": "0000-00-00T00:00:00.000Z",
    "createdBy": 0,
    "createdByName": "Name",
    "updatedAt": "0000-00-00T00:00:00.000Z",
    "updatedBy": 0,
    "updatedByName": "Name",
  },
  "state": {
    "value": "Unknown",
    "valueUnderMaintenance": "Unknown",
    "Timestamp": "0000-00-00T00:00:00.000Z"
  },
  "healthStatus": {
    "value": 0,
    "timestamp": "0000-00-00T00:00:00.000Z",
    "calculation": {
      "resultBy": "Direct",
      "direct": 0,
      "weight": 0
    }
  },
  "healthInfluence": {
    "value": 0,
    "maxInfluence": false
  },
  "incomingEdges": [{
    "type": "Hierarchy",
    "configItem": {
      "id": 0,
      "name": "Name"
    }
  }],
  "outgoingEdges": [{
    "type": "Hierarchy",
    "configItem": {
      "id": 0,
      "name": "Name"
    }
  }],
  "cmdbLinks": [{
    "instanceId": 0,
    "entityId": "Id",
    "labels": ["label"]
  }],
  "sharedToWorkGroups": [{
    "workGroupId": 0,
    "shareType": "ConfigItem",
    "grants": ["base-system.rsm.basic-read"]
  }]
}

# CI model fields

Field name Field type Field description
id number CI identifier.
name string CI name.
description string CI description.
parent object / null Parent CI. null, if CI a root.
ownerWorkGroup object Owner workgroup of CI
configItemType object CI type.
labels object / null Dictionary of CI labels
entityInfo object Meta-information for the entity.
state object / null Current status of CI. If the value is displayed.
healthStatus object / null Calculated health. If the value is displayed.
healthInfluence object / null Information on the health effects of CI. If the value is displayed.
cmdbSystem object / null A model of the CMDB system, on the basis of which created CI. If the value is displayed.
incomingEdges object[] Incoming links to other CI.
outgoingEdges object[] Outgoing links to other CI.
cmdbLinks object[] A list of links with entities external CMDB CI.
sharedToWorkGroups object[] Model list of rights for specific workgroups.

# Types of access rights

Type Description
ConfigItem Grant access rights for CI only.
Tree Grant access rights for the CI and its subordinated tree.
ChildrenTree Grant access rights only for the subordinate tree of this CI.

# Rights granted to workgroups

Access right Description
base-system.rsm.basic-read The right to read basic information.
base-system.rsm.monitoring-read The right to read CI bindings.
base-system.rsm.read The right to fully read CI.
base-system.rsm.write The right to fully access CI.