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.
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