Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/categories

Get catalog categories

Retrieves the complete hierarchical category structure for the catalog including item counts for each category. Categories are organized in a tree structure with parent-child relationships.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to query

Responses

200 Categories retrieved successfully
No categories

Catalog with no categories configured 

{
  "categories": [],
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_categories": 0
}
Single-level categories

Simple catalog with no subcategories 

{
  "categories": [
    {
      "categories": [],
      "category_id": 100,
      "display_name": "Gift Cards",
      "is_root": true,
      "num_items": 25,
      "parent_id": null
    },
    {
      "categories": [],
      "category_id": 200,
      "display_name": "Merchandise",
      "is_root": true,
      "num_items": 150,
      "parent_id": null
    },
    {
      "categories": [],
      "category_id": 300,
      "display_name": "Experiences",
      "is_root": true,
      "num_items": 45,
      "parent_id": null
    },
    {
      "categories": [],
      "category_id": 400,
      "display_name": "Digital Products",
      "is_root": true,
      "num_items": 30,
      "parent_id": null
    }
  ],
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_categories": 4
}
Multi-level category tree

Categories with nested subcategories 

{
  "categories": [
    {
      "categories": [
        {
          "categories": [
            {
              "categories": [],
              "category_id": 1011,
              "display_name": "Shirts",
              "is_root": false,
              "num_items": 80,
              "parent_id": 101
            },
            {
              "categories": [],
              "category_id": 1012,
              "display_name": "Pants",
              "is_root": false,
              "num_items": 60,
              "parent_id": 101
            }
          ],
          "category_id": 101,
          "display_name": "Men's Clothing",
          "is_root": false,
          "num_items": 200,
          "parent_id": 100
        },
        {
          "categories": [],
          "category_id": 102,
          "display_name": "Women's Clothing",
          "is_root": false,
          "num_items": 250,
          "parent_id": 100
        }
      ],
      "category_id": 100,
      "display_name": "Apparel",
      "is_root": true,
      "num_items": 450,
      "parent_id": null
    },
    {
      "categories": [],
      "category_id": 200,
      "display_name": "Electronics",
      "is_root": true,
      "num_items": 320,
      "parent_id": null
    }
  ],
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_categories": 8
}
Response Schema
Schema Reference:

Hierarchical list of catalog categories

Type: object
Required fields:
success timestamp total_categories categories

Properties:

categories required
success required
timestamp required
total_categories required
404 Socket not found
Socket doesn't exist 
{
  "error_code": "NOT_FOUND",
  "message": "The requested resource was not found.",
  "success": false,
  "timestamp": "2025-08-05T00:44:25.846238Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
503 Search service unavailable
Solr service unavailable 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Search service unavailable",
  "success": false,
  "timestamp": "2025-08-05T00:44:25.846238Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required