The ServiceNow CMDB Instance API provides REST endpoints for retrieving configuration item (CI) records from the Configuration Management Database by class name and sys_id. It is used to query and access infrastructure and application CI data stored in ServiceNow's CMDB.
openapi: 3.1.0
info:
title: ServiceNow CMDB Instance API
description: >-
The ServiceNow CMDB Instance API provides REST endpoints for retrieving
configuration item (CI) records from the Configuration Management Database
by class name and sys_id. It is used to query and access infrastructure
and application CI data stored in the ServiceNow CMDB for integration
with discovery tools and reporting systems.
version: 'Yokohama'
contact:
name: ServiceNow Support
url: https://support.servicenow.com
termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
description: ServiceNow CMDB Instance API Documentation
url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/cmdb-instance-api.html
servers:
- url: https://{instance}.service-now.com/api/now/cmdb
description: ServiceNow Instance
variables:
instance:
default: instance
description: Your ServiceNow instance name
tags:
- name: CMDB Instances
description: >-
Operations for retrieving configuration item instances from the CMDB
by class name.
security:
- basicAuth: []
- oauth2: []
paths:
/instance/{className}:
get:
operationId: listCmdbInstances
summary: Servicenow List Configuration Items by Class
description: >-
Retrieves a list of configuration item instances for the specified
CMDB class. Returns sys_id and name for each CI by default.
tags:
- CMDB Instances
parameters:
- name: className
in: path
required: true
description: >-
The CMDB class name to query, such as cmdb_ci_server,
cmdb_ci_linux_server, cmdb_ci_appl, or cmdb_ci_apache_web_server.
schema:
type: string
example: cmdb_ci_linux_server
- name: sysparm_query
in: query
required: false
description: >-
An encoded query string to filter CI records.
schema:
type: string
example: example_value
- name: sysparm_limit
in: query
required: false
description: Maximum number of records to return. Default is 1000.
schema:
type: integer
minimum: 1
default: 1000
example: 10
- name: sysparm_offset
in: query
required: false
description: Starting record index for pagination.
schema:
type: integer
minimum: 0
default: 0
example: 10
responses:
'200':
description: >-
Successful response returning a list of CI instances.
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/CmdbInstanceSummary'
examples:
Listcmdbinstances200Example:
summary: Default listCmdbInstances 200 response
x-microcks-default: true
value:
result:
- sys_id: '500123'
name: Example Title
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Listcmdbinstances401Example:
summary: Default listCmdbInstances 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'404':
description: The specified CMDB class does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Listcmdbinstances404Example:
summary: Default listCmdbInstances 404 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/instance/{className}/{sys_id}:
get:
operationId: getCmdbInstance
summary: Servicenow Retrieve a Specific Configuration Item
description: >-
Retrieves the full details of a specific configuration item by its
class name and sys_id. Returns all attributes of the CI record.
tags:
- CMDB Instances
parameters:
- name: className
in: path
required: true
description: The CMDB class name.
schema:
type: string
example: cmdb_ci_linux_server
- name: sys_id
in: path
required: true
description: The unique sys_id of the configuration item.
schema:
type: string
example: '500123'
responses:
'200':
description: Successful response returning the CI details.
content:
application/json:
schema:
type: object
properties:
result:
$ref: '#/components/schemas/CmdbInstance'
examples:
Getcmdbinstance200Example:
summary: Default getCmdbInstance 200 response
x-microcks-default: true
value:
result:
sys_id: '500123'
name: Example Title
sys_class_name: example_value
category: example_value
subcategory: example_value
operational_status: '1'
install_status: example_value
serial_number: example_value
asset_tag: example_value
ip_address: example_value
mac_address: example_value
dns_domain: example_value
fqdn: example_value
os: example_value
os_version: example_value
manufacturer: example_value
model_id: '500123'
location: example_value
department: example_value
company: example_value
assigned_to: example_value
managed_by: example_value
owned_by: example_value
support_group: example_value
sys_created_on: '2026-01-15T10:30:00Z'
sys_updated_on: '2026-01-15T10:30:00Z'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcmdbinstance401Example:
summary: Default getCmdbInstance 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'404':
description: Configuration item not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcmdbinstance404Example:
summary: Default getCmdbInstance 404 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication with ServiceNow credentials. Requires CMDB
read access.
oauth2:
type: oauth2
description: OAuth 2.0 authentication using ServiceNow's OAuth provider.
flows:
password:
tokenUrl: https://{instance}.service-now.com/oauth_token.do
scopes: {}
schemas:
CmdbInstanceSummary:
type: object
description: >-
A summary of a CMDB configuration item containing its identifier
and display name.
properties:
sys_id:
type: string
description: Unique identifier for the configuration item.
example: '500123'
name:
type: string
description: The display name of the configuration item.
example: Example Title
CmdbInstance:
type: object
description: >-
A full CMDB configuration item record. Fields vary by CI class but
common attributes are included below.
properties:
sys_id:
type: string
description: Unique identifier for the configuration item.
example: '500123'
name:
type: string
description: The display name of the configuration item.
example: Example Title
sys_class_name:
type: string
description: The CMDB class name for this CI.
example: example_value
category:
type: string
description: The category of the CI.
example: example_value
subcategory:
type: string
description: The subcategory of the CI.
example: example_value
operational_status:
type: string
description: >-
The operational status of the CI.
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
example: '1'
install_status:
type: string
description: The installation status of the CI.
example: example_value
serial_number:
type: string
description: The serial number of the hardware asset.
example: example_value
asset_tag:
type: string
description: The asset tag identifier.
example: example_value
ip_address:
type: string
description: The IP address of the CI.
example: example_value
mac_address:
type: string
description: The MAC address of the CI.
example: example_value
dns_domain:
type: string
description: The DNS domain of the CI.
example: example_value
fqdn:
type: string
description: The fully qualified domain name.
example: example_value
os:
type: string
description: The operating system.
example: example_value
os_version:
type: string
description: The operating system version.
example: example_value
manufacturer:
type: string
description: The sys_id of the manufacturer.
example: example_value
model_id:
type: string
description: The sys_id of the model.
example: '500123'
location:
type: string
description: The sys_id of the CI location.
example: example_value
department:
type: string
description: The sys_id of the department.
example: example_value
company:
type: string
description: The sys_id of the owning company.
example: example_value
assigned_to:
type: string
description: The sys_id of the assigned user.
example: example_value
managed_by:
type: string
description: The sys_id of the managing user.
example: example_value
owned_by:
type: string
description: The sys_id of the owner.
example: example_value
support_group:
type: string
description: The sys_id of the support group.
example: example_value
sys_created_on:
type: string
format: date-time
description: The date and time when the CI was created.
example: '2026-01-15T10:30:00Z'
sys_updated_on:
type: string
format: date-time
description: The date and time when the CI was last updated.
example: '2026-01-15T10:30:00Z'
additionalProperties: true
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: A human-readable error message.
detail:
type: string
description: Detailed information about the error.
example: example_value