openapi: 3.1.0
info:
  title: ServiceNow Service Catalog 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
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
servers:
- url: https://{instance}.service-now.com/api/sn_sc
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
tags:
- name: Cart
  description: >-
    Operations for managing the shopping cart and submitting orders.
- name: Catalog Items
  description: >-
    Operations for retrieving catalog item details and variables.
- name: Catalogs
  description: >-
    Operations for browsing and retrieving service catalogs.
- name: Categories
  description: >-
    Operations for browsing catalog categories.
security:
- basicAuth: []
- oauth2: []
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
  /servicecatalog/categories/{sys_id}:
    get:
      operationId: getCategory
      summary: Servicenow Retrieve a Catalog Category
      description: >-
        Retrieves details for a specific catalog category including its
        child categories and items.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '200':
          description: Successful response returning category details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Category'
              examples:
                Getcategory200Example:
                  summary: Default getCategory 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      title: Example Title
                      description: A sample description.
                      full_description: example_value
                      subcategories:
                      - sys_id: '500123'
                        title: Example Title
        '404':
          description: Category not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcategory404Example:
                  summary: Default getCategory 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /servicecatalog/items/{sys_id}/add_to_cart:
    post:
      operationId: addItemToCart
      summary: Servicenow Add a Catalog Item to the Cart
      description: >-
        Adds the specified catalog item to the shopping cart with the
        given quantity and variable values.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/sysId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItemInput'
            examples:
              AdditemtocartRequestExample:
                summary: Default addItemToCart request
                x-microcks-default: true
                value:
                  sysparm_quantity: 10
                  variables: example_value
      responses:
        '200':
          description: Item successfully added to the cart.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/CartItem'
              examples:
                Additemtocart200Example:
                  summary: Default addItemToCart 200 response
                  x-microcks-default: true
                  value:
                    result:
                      cart_item_id: '500123'
                      catalog_item_id: '500123'
                      quantity: 10
                      subtotal: 42
        '400':
          description: Bad request. Required variables are missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Additemtocart400Example:
                  summary: Default addItemToCart 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /servicecatalog/items/{sys_id}/order_now:
    post:
      operationId: orderItemNow
      summary: Servicenow Order a Catalog Item Immediately
      description: >-
        Orders the specified catalog item without going through the cart.
        Creates a request directly with the given quantity and variable values.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/sysId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItemInput'
            examples:
              OrderitemnowRequestExample:
                summary: Default orderItemNow request
                x-microcks-default: true
                value:
                  sysparm_quantity: 10
                  variables: example_value
      responses:
        '200':
          description: Order successfully submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/OrderResult'
              examples:
                Orderitemnow200Example:
                  summary: Default orderItemNow 200 response
                  x-microcks-default: true
                  value:
                    result:
                      request_number: example_value
                      request_id: '500123'
                      table: example_value
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Orderitemnow400Example:
                  summary: Default orderItemNow 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /servicecatalog/cart:
    get:
      operationId: getCart
      summary: Servicenow Retrieve the Current Cart
      description: >-
        Retrieves the contents of the current user's shopping cart.
      tags:
      - Cart
      responses:
        '200':
          description: Successful response returning cart contents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Cart'
              examples:
                Getcart200Example:
                  summary: Default getCart 200 response
                  x-microcks-default: true
                  value:
                    result:
                      items:
                      - {}
                      subtotal: 42
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getcart401Example:
                  summary: Default getCart 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: emptyCart
      summary: Servicenow Empty the Cart
      description: >-
        Removes all items from the current user's shopping cart.
      tags:
      - Cart
      responses:
        '200':
          description: Cart successfully emptied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
              examples:
                Emptycart200Example:
                  summary: Default emptyCart 200 response
                  x-microcks-default: true
                  value:
                    result: example_value
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Emptycart401Example:
                  summary: Default emptyCart 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /servicecatalog/cart/submit_order:
    post:
      operationId: submitCartOrder
      summary: Servicenow Submit the Cart as an Order
      description: >-
        Submits all items in the current user's shopping cart as a service
        catalog request. Returns the request number and details.
      tags:
      - Cart
      responses:
        '200':
          description: Order successfully submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/OrderResult'
              examples:
                Submitcartorder200Example:
                  summary: Default submitCartOrder 200 response
                  x-microcks-default: true
                  value:
                    result:
                      request_number: example_value
                      request_id: '500123'
                      table: example_value
        '400':
          description: Cart is empty or contains invalid items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Submitcartorder400Example:
                  summary: Default submitCartOrder 400 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.
    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: {}
  parameters:
    sysId:
      name: sys_id
      in: path
      required: true
      description: The unique system identifier.
      schema:
        type: string
  schemas:
    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
    Category:
      type: object
      description: A catalog category.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the category.
          example: '500123'
        title:
          type: string
          description: The display title of the category.
          example: Example Title
        description:
          type: string
          description: A description of the category.
          example: A sample description.
        full_description:
          type: string
          description: The full description of the category.
          example: example_value
        subcategories:
          type: array
          description: Child categories.
          items:
            type: object
            properties:
              sys_id:
                type: string
              title:
                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
    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: []
    CartItemInput:
      type: object
      description: Input for adding a catalog item to the cart or ordering directly.
      required:
      - sysparm_quantity
      properties:
        sysparm_quantity:
          type: integer
          minimum: 1
          description: The quantity of items to order.
          example: 10
        variables:
          type: object
          description: >-
            Name-value pairs for the catalog item variables. Keys are variable
            names and values are the user-provided entries.
          additionalProperties:
            type: string
          example: example_value
    CartItem:
      type: object
      description: An item in the shopping cart.
      properties:
        cart_item_id:
          type: string
          description: Unique identifier for the cart item.
          example: '500123'
        catalog_item_id:
          type: string
          description: The sys_id of the catalog item.
          example: '500123'
        quantity:
          type: integer
          description: The quantity ordered.
          example: 10
        subtotal:
          type: string
          description: The subtotal for this cart item.
          example: 42
    Cart:
      type: object
      description: The shopping cart contents.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
          example: []
        subtotal:
          type: string
          description: The cart subtotal.
          example: 42
    OrderResult:
      type: object
      description: The result of a submitted catalog order.
      properties:
        request_number:
          type: string
          description: The generated request number.
          example: example_value
        request_id:
          type: string
          description: The sys_id of the request record.
          example: '500123'
        table:
          type: string
          description: The table name where the request is stored.
          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