openapi: 3.1.0
info:
  title: ServiceNow Contact Aggregate Statistics CMDB Instances API
  description: 'The Contact API provides endpoints that enable you to retrieve and update Customer Service Management (CSM) contact records.


    In addition, you can generate new social media profile records when creating a contact.


    The Contact API requires the Customer Service plugin (com.sn_customerservice) and is provided within the now namespace.


    **Authentication**: Users need the `csm_ws_integration` role for full API access.

    '
  version: Zurich
  contact:
    name: ServiceNow
    url: https://docs.servicenow.com
  x-namespace: now
servers:
- url: https://{instance}.servicenow.com/api/now
  description: ServiceNow instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
tags:
- name: CMDB Instances
  description: Operations for retrieving configuration item instances from the CMDB by class name.
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:
  schemas:
    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
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. User must have the csm_ws_integration role.