ServiceNow Catalogs API

openapi: 3.2.0
info:
  title: ServiceNow Service Catalog Catalogs 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: Catalogs
  description: Operations for browsing and retrieving service catalogs.
paths:
  /servicecatalog/catalogs:
    get:
      operationId: listCatalogs
      summary: Servicenow List Service Catalogs
      description: Retrieves a list of all available service catalogs on the instance.
      tags:
      - Catalogs
      parameters:
      - name: sysparm_limit
        in: query
        required: false
        description: Maximum number of catalogs 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 available catalogs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Catalog'
              examples:
                Listcatalogs200Example:
                  summary: Default listCatalogs 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      title: Example Title
                      description: A sample description.
                      has_categories: true
                      has_items: true
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listcatalogs401Example:
                  summary: Default listCatalogs 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /servicecatalog/catalogs/{sys_id}:
    get:
      operationId: getCatalog
      summary: Servicenow Retrieve a Specific Catalog
      description: Retrieves details for a specific service catalog including its categories.
      tags:
      - Catalogs
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '200':
          description: Successful response returning the catalog details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Catalog'
              examples:
                Getcatalog200Example:
                  summary: Default getCatalog 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      title: Example Title
                      description: A sample description.
                      has_categories: true
                      has_items: true
        '404':
          description: Catalog not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcatalog404Example:
                  summary: Default getCatalog 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
    Catalog:
      type: object
      description: A ServiceNow service catalog.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the catalog.
          example: '500123'
        title:
          type: string
          description: The display title of the catalog.
          example: Example Title
        description:
          type: string
          description: A description of the catalog.
          example: A sample description.
        has_categories:
          type: boolean
          description: Whether the catalog has categories.
          example: true
        has_items:
          type: boolean
          description: Whether the catalog has items.
          example: true
  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