ServiceNow Catalog Items API

openapi: 3.2.0
info:
  title: ServiceNow Service Catalog Catalog Items API
  description: The ServiceNow Service Catalog API provides REST endpoints for browsing catalog categories and items, retrieving catalog item details and variables, and submitting catalog requests. It enables external applications and portals to integrate with ServiceNow's self-service request capabilities including catalog browsing, cart management, and order submission.
  version: Yokohama
  contact:
    name: ServiceNow Support
    url: https://support.servicenow.com
  termsOfService: https://www.servicenow.com/terms-of-use.html
servers:
- url: https://{instance}.service-now.com/api/sn_sc
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
- oauth2: []
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:
    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
    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: []
    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: []
    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
  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.
    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: {}
externalDocs:
  description: ServiceNow Service Catalog API Documentation
  url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_ServiceCatalogAPI.html