ServiceNow Catalog Items API

openapi: 3.1.0
info:
  title: ServiceNow Contact Aggregate Statistics Catalog Items 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: Catalog Items
  description: Operations for retrieving catalog item details and variables.
paths:
  /servicecatalog/items:
    get:
      operationId: listCatalogItems
      summary: Servicenow List Catalog Items
      description: Retrieves a list of catalog items. Supports filtering by catalog and category.
      tags:
      - Catalog Items
      parameters:
      - name: sysparm_catalog
        in: query
        required: false
        description: The sys_id of the catalog to filter items by.
        schema:
          type: string
        example: example_value
      - name: sysparm_category
        in: query
        required: false
        description: The sys_id of the category to filter items by.
        schema:
          type: string
        example: example_value
      - name: sysparm_limit
        in: query
        required: false
        description: Maximum number of items to return.
        schema:
          type: integer
          minimum: 1
        example: 10
      - name: sysparm_offset
        in: query
        required: false
        description: Starting index for pagination.
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 10
      responses:
        '200':
          description: Successful response returning catalog items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogItem'
              examples:
                Listcatalogitems200Example:
                  summary: Default listCatalogItems 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      name: Example Title
                      short_description: example_value
                      category: example_value
                      price: example_value
                      picture: example_value
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listcatalogitems401Example:
                  summary: Default listCatalogItems 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /servicecatalog/items/{sys_id}:
    get:
      operationId: getCatalogItem
      summary: Servicenow Retrieve a Catalog Item
      description: Retrieves details for a specific catalog item including its variables and pricing information.
      tags:
      - Catalog Items
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '200':
          description: Successful response returning item details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/CatalogItemDetail'
              examples:
                Getcatalogitem200Example:
                  summary: Default getCatalogItem 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      name: Example Title
                      short_description: example_value
                      description: A sample description.
                      category: example_value
                      price: example_value
                      picture: example_value
                      mandatory_attachment: true
                      request_method: example_value
                      variables:
                      - {}
        '404':
          description: Catalog item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcatalogitem404Example:
                  summary: Default getCatalogItem 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CatalogItem:
      type: object
      description: A catalog item summary.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the catalog item.
          example: '500123'
        name:
          type: string
          description: The display name of the item.
          example: Example Title
        short_description:
          type: string
          description: A brief description of the item.
          example: example_value
        category:
          type: string
          description: The category sys_id.
          example: example_value
        price:
          type: string
          description: The displayed price of the item.
          example: example_value
        picture:
          type: string
          description: URL to the item picture.
          example: example_value
    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
    CatalogVariable:
      type: object
      description: A variable on a catalog item form.
      properties:
        name:
          type: string
          description: The internal name of the variable.
          example: Example Title
        label:
          type: string
          description: The display label.
          example: Example Title
        type:
          type: string
          description: The variable type.
          example: example_value
        mandatory:
          type: boolean
          description: Whether the variable is required.
          example: true
        default_value:
          type: string
          description: The default value.
          example: example_value
        choices:
          type: array
          description: Available choices for select-type variables.
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
          example: []
    CatalogItemDetail:
      type: object
      description: Full details of a catalog item including its variables.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the catalog item.
          example: '500123'
        name:
          type: string
          description: The display name of the item.
          example: Example Title
        short_description:
          type: string
          description: A brief description of the item.
          example: example_value
        description:
          type: string
          description: The full description of the item.
          example: A sample description.
        category:
          type: string
          description: The category sys_id.
          example: example_value
        price:
          type: string
          description: The displayed price.
          example: example_value
        picture:
          type: string
          description: URL to the item picture.
          example: example_value
        mandatory_attachment:
          type: boolean
          description: Whether a file attachment is required to order the item.
          example: true
        request_method:
          type: string
          description: The method used to fulfill the request.
          example: example_value
        variables:
          type: array
          description: The list of variables (form fields) that must be filled in when ordering the item.
          items:
            $ref: '#/components/schemas/CatalogVariable'
          example: []
  parameters:
    sysId:
      name: sys_id
      in: path
      required: true
      description: The unique system identifier.
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication with ServiceNow credentials. User must have the csm_ws_integration role.