Service Catalog

The service catalog is the storefront for IT and enterprise services available to your organization. Each catalog item defines a requestable service — from laptop provisioning to VPN access — with a structured form schema, approval workflows, and SLA policies. On this page, we'll dive into the different catalog endpoints you can use to browse, create, update, and request services programmatically.

The catalog item model

The catalog item model contains all the information about a requestable service, including its category, form schema for request intake, approval requirements, and fulfillment expectations.

Properties

Name
id
Type
string
Description
Unique identifier for the catalog item (UUID).
Name
name
Type
string
Description
Display name of the catalog item.
Name
description
Type
string
Description
Detailed description of the service offered.
Name
category
Type
string
Description
Top-level category (e.g., Hardware, Software, Access, Network).
Name
subcategory
Type
string
Description
Subcategory within the parent category (e.g., Laptop, License, VPN).
Name
icon_url
Type
string
Description
URL to the icon image displayed in the self-service portal.
Name
form_schema
Type
object
Description
JSON Schema defining the request form fields presented to the requester.
Name
approval_required
Type
boolean
Description
Whether this catalog item requires manager or CAB approval before fulfillment.
Name
default_assignee_team
Type
string
Description
The team ID that receives requests for this catalog item by default.
Name
sla_policy_id
Type
string
Description
The SLA policy ID applied to requests created from this catalog item.
Name
estimated_fulfillment_time
Type
string
Description
Human-readable estimated time to fulfill (e.g., 2 business days, 4 hours).
Name
status
Type
string
Description
Catalog item lifecycle status. One of active, draft, or archived.
Name
tags
Type
array
Description
An array of string tags for search and filtering.
Name
created_at
Type
timestamp
Description
Timestamp of when the catalog item was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the catalog item was last updated.
Name
org_id
Type
string
Description
The tenant organization ID that owns this catalog item.

GET/v1/catalog

List all catalog items

This endpoint allows you to retrieve a paginated list of all service catalog items in your organization. By default, a maximum of ten items are shown per page. You can filter by category, status, and tags.

Optional attributes

Name
category
Type
string
Description
Filter catalog items by category (e.g., Hardware, Software).
Name
subcategory
Type
string
Description
Filter catalog items by subcategory (e.g., Laptop, VPN).
Name
status
Type
string
Description
Filter by catalog item status. One of active, draft, or archived.
Name
tags
Type
string
Description
Comma-separated list of tags to filter by.
Name
search
Type
string
Description
Full-text search across name and description.
Name
page
Type
integer
Description
The page number for pagination.
Name
limit
Type
integer
Description
Limit the number of catalog items returned per page.

Request

GET

/v1/catalog

curl -G http://localhost:3000/v1/catalog \
  -H "Authorization: Bearer {token}" \
  -d category=Hardware \
  -d status=active \
  -d limit=10

Response

{
  "has_more": true,
  "page": 1,
  "limit": 10,
  "data": [
    {
      "id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Laptop Provisioning",
      "description": "Request a new laptop for a new hire or replacement. Includes standard enterprise image, security agent, and VPN client pre-installed.",
      "category": "Hardware",
      "subcategory": "Laptop",
      "icon_url": "https://assets.example.com/icons/laptop.svg",
      "form_schema": {
        "type": "object",
        "required": ["employee_name", "department", "laptop_model"],
        "properties": {
          "employee_name": { "type": "string", "title": "Employee Name" },
          "department": { "type": "string", "title": "Department" },
          "laptop_model": {
            "type": "string",
            "title": "Laptop Model",
            "enum": ["ThinkPad T14s", "ThinkPad X1 Carbon", "MacBook Pro 14"]
          },
          "special_software": { "type": "string", "title": "Special Software Requirements" }
        }
      },
      "approval_required": true,
      "default_assignee_team": "team_desktop_eng",
      "sla_policy_id": "sla_hardware_standard",
      "estimated_fulfillment_time": "3 business days",
      "status": "active",
      "tags": ["hardware", "onboarding", "laptop"],
      "created_at": 1708700000,
      "updated_at": 1708750000,
      "org_id": "org_9f8e7d6c5b4a"
    },
    {
      "id": "cat_b2c3d4e5-f6a7-8901-bcde-f12345678901"
      // ...
    }
  ]
}

POST/v1/catalog

Create a catalog item

This endpoint allows you to create a new service catalog item. You must provide a name, description, and category at minimum. New items default to draft status and must be explicitly set to active to appear in the self-service portal.

Required attributes

Name
name
Type
string
Description
Display name of the catalog item.
Name
description
Type
string
Description
Detailed description of the service offered.
Name
category
Type
string
Description
Top-level category for the catalog item.

Optional attributes

Name
subcategory
Type
string
Description
Subcategory within the parent category.
Name
icon_url
Type
string
Description
URL to the icon image for the self-service portal.
Name
form_schema
Type
object
Description
JSON Schema defining the request intake form fields.
Name
approval_required
Type
boolean
Description
Whether approval is needed before fulfillment. Defaults to false.
Name
default_assignee_team
Type
string
Description
The team ID that receives requests by default.
Name
sla_policy_id
Type
string
Description
The SLA policy ID to apply to requests from this item.
Name
estimated_fulfillment_time
Type
string
Description
Human-readable estimated fulfillment time.
Name
status
Type
string
Description
Initial status. Defaults to draft. One of active, draft, or archived.
Name
tags
Type
array
Description
An array of string tags for search and filtering.

Request

POST

/v1/catalog

curl http://localhost:3000/v1/catalog \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VPN Access Request",
    "description": "Request VPN access for remote work. Includes GlobalProtect client setup and split-tunnel configuration.",
    "category": "Network",
    "subcategory": "VPN",
    "approval_required": false,
    "default_assignee_team": "team_network_ops",
    "sla_policy_id": "sla_network_standard",
    "estimated_fulfillment_time": "4 hours",
    "status": "active",
    "tags": ["network", "vpn", "remote-access"],
    "form_schema": {
      "type": "object",
      "required": ["employee_name", "access_reason"],
      "properties": {
        "employee_name": { "type": "string", "title": "Employee Name" },
        "access_reason": { "type": "string", "title": "Reason for Access" },
        "start_date": { "type": "string", "format": "date", "title": "Start Date" }
      }
    }
  }'

Response

{
  "id": "cat_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "VPN Access Request",
  "description": "Request VPN access for remote work. Includes GlobalProtect client setup and split-tunnel configuration.",
  "category": "Network",
  "subcategory": "VPN",
  "icon_url": null,
  "form_schema": {
    "type": "object",
    "required": ["employee_name", "access_reason"],
    "properties": {
      "employee_name": { "type": "string", "title": "Employee Name" },
      "access_reason": { "type": "string", "title": "Reason for Access" },
      "start_date": { "type": "string", "format": "date", "title": "Start Date" }
    }
  },
  "approval_required": false,
  "default_assignee_team": "team_network_ops",
  "sla_policy_id": "sla_network_standard",
  "estimated_fulfillment_time": "4 hours",
  "status": "active",
  "tags": ["network", "vpn", "remote-access"],
  "created_at": 1708790400,
  "updated_at": 1708790400,
  "org_id": "org_9f8e7d6c5b4a"
}

GET/v1/catalog/:id

Retrieve a catalog item

This endpoint allows you to retrieve a catalog item by providing its UUID. Refer to the catalog item model at the top of this page to see which properties are included with catalog item objects.

Request

GET

/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl http://localhost:3000/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Laptop Provisioning",
  "description": "Request a new laptop for a new hire or replacement. Includes standard enterprise image, security agent, and VPN client pre-installed.",
  "category": "Hardware",
  "subcategory": "Laptop",
  "icon_url": "https://assets.example.com/icons/laptop.svg",
  "form_schema": {
    "type": "object",
    "required": ["employee_name", "department", "laptop_model"],
    "properties": {
      "employee_name": { "type": "string", "title": "Employee Name" },
      "department": { "type": "string", "title": "Department" },
      "laptop_model": {
        "type": "string",
        "title": "Laptop Model",
        "enum": ["ThinkPad T14s", "ThinkPad X1 Carbon", "MacBook Pro 14"]
      },
      "special_software": { "type": "string", "title": "Special Software Requirements" }
    }
  },
  "approval_required": true,
  "default_assignee_team": "team_desktop_eng",
  "sla_policy_id": "sla_hardware_standard",
  "estimated_fulfillment_time": "3 business days",
  "status": "active",
  "tags": ["hardware", "onboarding", "laptop"],
  "created_at": 1708700000,
  "updated_at": 1708750000,
  "org_id": "org_9f8e7d6c5b4a"
}

PATCH/v1/catalog/:id

Update a catalog item

This endpoint allows you to perform a partial update on a catalog item. You can update any mutable field including name, description, form schema, approval settings, and status. Setting status to archived removes the item from the self-service portal but preserves existing requests.

Optional attributes

Name
name
Type
string
Description
Updated display name.
Name
description
Type
string
Description
Updated service description.
Name
category
Type
string
Description
Updated top-level category.
Name
subcategory
Type
string
Description
Updated subcategory.
Name
icon_url
Type
string
Description
Updated icon URL.
Name
form_schema
Type
object
Description
Updated JSON Schema for the request form.
Name
approval_required
Type
boolean
Description
Update whether approval is required.
Name
default_assignee_team
Type
string
Description
Update the default assignee team.
Name
sla_policy_id
Type
string
Description
Update the SLA policy.
Name
estimated_fulfillment_time
Type
string
Description
Updated estimated fulfillment time.
Name
status
Type
string
Description
Update the item status. One of active, draft, or archived.
Name
tags
Type
array
Description
Updated array of tags.

Request

PATCH

/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X PATCH http://localhost:3000/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "estimated_fulfillment_time": "2 business days",
    "approval_required": false,
    "tags": ["hardware", "onboarding", "laptop", "fast-track"]
  }'

Response

{
  "id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Laptop Provisioning",
  "description": "Request a new laptop for a new hire or replacement. Includes standard enterprise image, security agent, and VPN client pre-installed.",
  "category": "Hardware",
  "subcategory": "Laptop",
  "icon_url": "https://assets.example.com/icons/laptop.svg",
  "form_schema": {
    "type": "object",
    "required": ["employee_name", "department", "laptop_model"],
    "properties": {
      "employee_name": { "type": "string", "title": "Employee Name" },
      "department": { "type": "string", "title": "Department" },
      "laptop_model": {
        "type": "string",
        "title": "Laptop Model",
        "enum": ["ThinkPad T14s", "ThinkPad X1 Carbon", "MacBook Pro 14"]
      },
      "special_software": { "type": "string", "title": "Special Software Requirements" }
    }
  },
  "approval_required": false,
  "default_assignee_team": "team_desktop_eng",
  "sla_policy_id": "sla_hardware_standard",
  "estimated_fulfillment_time": "2 business days",
  "status": "active",
  "tags": ["hardware", "onboarding", "laptop", "fast-track"],
  "created_at": 1708700000,
  "updated_at": 1708795000,
  "org_id": "org_9f8e7d6c5b4a"
}

DELETE/v1/catalog/:id

Delete a catalog item

This endpoint allows you to delete a catalog item. Note: deleting a catalog item is a permanent action. In most workflows, you should set the status to archived instead of deleting, which preserves the item for historical reference while hiding it from the self-service portal. Existing open requests created from a deleted catalog item will remain active.

Request

DELETE

/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X DELETE http://localhost:3000/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

GET/v1/catalog/categories

List all categories

This endpoint returns all distinct categories and their subcategories currently in use across your organization's service catalog. This is useful for building category navigation in the self-service portal.

Request

GET

/v1/catalog/categories

curl http://localhost:3000/v1/catalog/categories \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "category": "Hardware",
      "subcategories": ["Laptop", "Monitor", "Peripheral", "Mobile Device"],
      "item_count": 12
    },
    {
      "category": "Software",
      "subcategories": ["License", "Installation", "SaaS Access"],
      "item_count": 24
    },
    {
      "category": "Access",
      "subcategories": ["Active Directory", "Application Access", "Privileged Access"],
      "item_count": 8
    },
    {
      "category": "Network",
      "subcategories": ["VPN", "Wi-Fi", "Firewall Rule", "DNS"],
      "item_count": 6
    }
  ]
}

POST/v1/catalog/:id/request

Submit a service request

This endpoint allows you to submit a service request from a specific catalog item. The request body must conform to the form_schema defined on the catalog item. A new ticket of type service_request is created automatically, the appropriate SLA policy is applied, and the request is routed to the default assignee team. If the catalog item has approval_required set to true, the request enters an approval workflow before fulfillment begins.

Required attributes

Name
form_data
Type
object
Description
An object containing the form field values, validated against the catalog item's form_schema.

Optional attributes

Name
urgency
Type
string
Description
Requester-indicated urgency. One of low, medium, or high. Used to influence priority calculation.
Name
additional_notes
Type
string
Description
Free-text notes from the requester providing extra context.

Request

POST

/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890/request

curl http://localhost:3000/v1/catalog/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890/request \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "form_data": {
      "employee_name": "Alex Chen",
      "department": "Engineering",
      "laptop_model": "ThinkPad X1 Carbon",
      "special_software": "Docker Desktop, JetBrains IntelliJ IDEA"
    },
    "urgency": "medium",
    "additional_notes": "New hire starting on March 1st. Please have ready by February 28th if possible."
  }'

Response

{
  "id": "req_d4e5f6a7-b8c9-0123-def0-456789012345",
  "catalog_item_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "catalog_item_name": "Laptop Provisioning",
  "ticket_id": "tkt_e5f6a7b8-c9d0-1234-ef01-567890123456",
  "ticket_number": "REQ-00089",
  "requester_id": "usr_a1b2c3d4e5f6",
  "status": "pending_approval",
  "form_data": {
    "employee_name": "Alex Chen",
    "department": "Engineering",
    "laptop_model": "ThinkPad X1 Carbon",
    "special_software": "Docker Desktop, JetBrains IntelliJ IDEA"
  },
  "urgency": "medium",
  "additional_notes": "New hire starting on March 1st. Please have ready by February 28th if possible.",
  "approval_required": true,
  "sla_policy_id": "sla_hardware_standard",
  "estimated_fulfillment_time": "3 business days",
  "created_at": 1708790400,
  "updated_at": 1708790400
}