Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/brands

Get catalog brands

Retrieves all brands available in the catalog along with the number of items from each brand. Useful for creating brand-based filtering interfaces.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to query

Responses

200 Brands retrieved successfully
No brands available

Response when catalog has no brands defined 

{
  "brands": [],
  "success": true,
  "timestamp": "2025-08-08T10:15:30.123Z",
  "total_brands": 0
}
Small catalog with few brands

Response for a specialized catalog with limited brands 

{
  "brands": [
    {
      "brand_id": 501,
      "display_name": "Premium Brands",
      "num_items": 450
    },
    {
      "brand_id": 502,
      "display_name": "House Brand",
      "num_items": 320
    },
    {
      "brand_id": 503,
      "display_name": "Clearance Items",
      "num_items": 89
    }
  ],
  "success": true,
  "timestamp": "2025-08-08T10:15:30.123Z",
  "total_brands": 3
}
Multiple brands with varied item counts

Typical response showing various brands in the catalog 

{
  "brands": [
    {
      "brand_id": 101,
      "display_name": "Nike",
      "num_items": 145
    },
    {
      "brand_id": 102,
      "display_name": "Adidas",
      "num_items": 98
    },
    {
      "brand_id": 103,
      "display_name": "Under Armour",
      "num_items": 67
    },
    {
      "brand_id": 201,
      "display_name": "Apple",
      "num_items": 42
    },
    {
      "brand_id": 202,
      "display_name": "Samsung",
      "num_items": 89
    },
    {
      "brand_id": 301,
      "display_name": "Gift Card Express",
      "num_items": 25
    },
    {
      "brand_id": 302,
      "display_name": "Vanilla Gift",
      "num_items": 12
    },
    {
      "brand_id": 401,
      "display_name": "Generic",
      "num_items": 234
    }
  ],
  "success": true,
  "timestamp": "2025-08-08T10:15:30.123Z",
  "total_brands": 8
}
Response Schema
Schema Reference:

List of catalog brands with item counts

Type: object
Required fields:
success timestamp total_brands brands

Properties:

brands required
success required
timestamp required
total_brands required
404 Socket not found
Example Response 
{
  "error_code": "SOCKET_NOT_FOUND",
  "message": "Socket with ID 999 not found for this customer",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
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
Example Response 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Search service is temporarily unavailable",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
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