Search Catalog Items in Your Account

GET /public/catalog — Search catalog items by text, category, brand, and stock status. Returns items with pricing, images, and category hierarchy.

The Catalog search endpoint provides full access to the Portal.io catalog with rich filtering options. You can narrow results by free-text search, category hierarchy (CategoryId, CategoryIds, ParentCategoryId, ParentCategoryIds), brand, supplier, industry, price range, stock availability, favorites, and item type. CategoryId and CategoryIds are mutually exclusive, as are ParentCategoryId and ParentCategoryIds. When SearchText is omitted it is treated as an empty string. ItemType defaults to Part.

The Catalog endpoints require separate authorization. Contact your Portal.io representative to confirm your account has catalog API access enabled.

Request

GET /public/catalog

Headers

Accept · string · required

Must be application/json.

X-MSS-API-APPID · string · required

Your API Application Key.

X-MSS-API-USERKEY · string · required

Your User API Key.

X-MSS-CUSTOM-DATE · string · required

Current UTC timestamp in RFC 7231 format (e.g. Mon, 06 Apr 2026 00:22:19 GMT).

X-MSS-SIGNATURE · string · required

HMAC-SHA256 signature of the canonical request, Base64-encoded.

Query Parameters

SearchText · string

Free-text search string matched against item names, brands, and descriptions. Treated as empty string when omitted.

CategoryId · integer

Filter by a single category ID. Mutually exclusive with CategoryIds.

CategoryIds · array

Filter by multiple category IDs. Repeat the parameter for each value. Mutually exclusive with CategoryId.

ParentCategoryId · integer

Filter by a single parent category ID. Mutually exclusive with ParentCategoryIds.

ParentCategoryIds · array

Filter by multiple parent category IDs. Repeat the parameter for each value. Mutually exclusive with ParentCategoryId.

Brands · array

Filter by brand names. Repeat the parameter for each value.

Suppliers · array

Filter by supplier names. Repeat the parameter for each value.

Industries · array

Filter by industry tags. Repeat the parameter for each value.

ItemType · string

Type of item to return. One of Part, Labor, or CustomItem. Defaults to Part.

IsFavorite · boolean

When true, returns only items marked as favorites in your account.

IsInStock · boolean

When true, returns only items currently in stock.

IsAuthorized · boolean

When true, returns only items your account is authorized to sell.

IsDiscontinued · boolean

When true, includes discontinued items. Defaults to excluding them.

IsIndustrialFavorite · boolean

When true, returns only industrial favorite items.

MinMsrp · number

Filter for items with an MSRP greater than or equal to this value.

MaxMsrp · number

Filter for items with an MSRP less than or equal to this value.

IncludeImageUrl · boolean

When true, includes the item image URL in the response.

PageNumber · integer

1-based page index. Defaults to 1. Must be 1 or greater — negative values return a 400 error.

PageSize · integer

Number of items per page. Defaults to 10.

Response

200 Success

items · array

Array of catalog item objects matching the search criteria.

Show Catalog item object

id · integer

Unique numeric identifier of the catalog item.

brand · string

Manufacturer or brand name.

model · string

Model number or name.

shortDescription · string

Brief description of the item.

primaryImageUrl · string

URL of the item’s primary product image.

parentCategoryId · integer

ID of the item’s parent (industry-level) category.

categoryId · integer

ID of the item’s direct category.

categories · array

Array of category name strings describing the item’s category path.

isFavorite · boolean

true if the item is marked as a favorite in your account.

isDiscontinued · boolean

true if the item has been discontinued.

msrp · object

MSRP pricing object containing msrpUsd, value, regularValue, isCustom, currency, lastModifiedDate, and optional futurePrice.

defaultCost · object

Default supplier cost object containing supplierName, supplierSku, value, isInStock, isPromo, managePriceStatus, accountNumber, currency, and lastVerifiedDate.

totalItemCount · integer · required

Total number of items matching the query (across all pages). Use for pagination calculations.

processingTimeMS · integer · required

Search processing time in milliseconds.

favoriteItemCount · integer · required

Total number of favorite items matching the search criteria.

favoriteItems · array

Favorite catalog part items matching the search criteria. Same structure as items. Only populated when IsFavorite=true.

categoryFacets · array

Category facet values with result counts. Each entry contains a category name and the number of matching items.

brandFacets · array

Brand facet values with result counts. Each entry contains a brand name and the number of matching items.

supplierFacets · array

Supplier facet values with result counts. Each entry contains a supplier name and the number of matching items.

labors · array

Labor library items matching the search criteria. Returned when ItemType=Labor.

customItems · array

Custom library items matching the search criteria. Returned when ItemType=CustomItem.

Error Codes

Code	Meaning
401	Not authorized. Your HMAC signature was incorrect or credentials are invalid.
402	An active Portal.io subscription is required to use this endpoint.
403	Your user account does not have permission for this API call.
500	Internal server error.

Example

curl

curl -i -X GET \
  'https://api.portal.io/public/catalog?SearchText=receiver&PageNumber=1&PageSize=10' \
  -H 'Accept: application/json' \
  -H 'X-MSS-API-APPID: YOUR_APP_ID' \
  -H 'X-MSS-API-USERKEY: YOUR_USER_KEY' \
  -H 'X-MSS-CUSTOM-DATE: Mon, 06 Apr 2026 00:22:19 GMT' \
  -H 'X-MSS-SIGNATURE: BASE64_SIGNATURE'

200

{
  "items": [
    {
      "id": 8821,
      "brand": "Denon",
      "model": "AVR-X3800H",
      "shortDescription": "9.4-Channel 105W 8K AV Receiver",
      "primaryImageUrl": "https://images.portal.io/catalog/8821/primary.jpg",
      "parentCategoryId": 12,
      "categoryId": 47,
      "categories": ["Audio", "AV Receivers"],
      "isFavorite": false,
      "isDiscontinued": false,
      "msrp": {
        "msrpUsd": 1299.00,
        "value": 1299.00,
        "regularValue": 1299.00,
        "isCustom": false,
        "currency": { "code": "USD", "symbol": "$" },
        "lastModifiedDate": "2026-01-15T00:00:00Z"
      },
      "defaultCost": {
        "supplierName": "D&H Distributing",
        "supplierSku": "AVR-X3800H",
        "value": 975.00,
        "isInStock": true,
        "isPromo": false,
        "currency": { "code": "USD", "symbol": "$" }
      }
    }
  ],
  "totalItemCount": 1,
  "processingTimeMS": 42,
  "favoriteItemCount": 0,
  "favoriteItems": [],
  "categoryFacets": [
    { "value": "AV Receivers", "count": 1 }
  ],
  "brandFacets": [
    { "value": "Denon", "count": 1 }
  ],
  "supplierFacets": [
    { "value": "D&H Distributing", "count": 1 }
  ],
  "labors": [],
  "customItems": []
}