BizKitHub
DocsAPI ReferenceProduct/api/v1/product/feed
getProductPublic API v1

/api/v1/product/feed

Load full list of products from organisation database. By default, we only return basic properties for all products. If you want to return entire products, you need to specify additional properties.

Default properties (contains in all returned products): id, name, slug, shortDescription, mainImageUrl, mainImageThumbUrl, mainImageCardUrl, mainCategory, price, priceWithoutVat, vat, position, active, soldOut, warehouseAllQuantity, warehouseLimit, customFields, event.

productgetApiV1ProductFeed

Parameters

8 query

Query parameters

· 8
apiKeystringRequired

Your BizKitHub API key (passed as GET parameter).

Key format: A 32-character string matching: ^(PROD|DEV_|ROOT)[A-Za-z0-9]{28}$
Prefixes: PROD (production key), DEV_ (individual developer), ROOT (system key with no limits). Learn more

ExamplePRODPGrFxpGEtrOZfuWhnoJohUYBXuOE
querystringOptional

Search query

Exampleiphone
localestringOptional

Locale code (e.g. "cs", "en"). Returns translated read models for the given locale with fallback to default.

Examplecs
orderBystringOptional

Order by indexed internal field.

Supported values: position, price, priceDesc, eventDate.

Default: position
Exampleposition
categorystringOptional

Filter products from category by slug.

Examplesmartphone
pagestringOptional
Default: 1
Example1
limitstringOptional
Default: 32
Example32
propertiesstringOptional

Add extra on demand properties separated by semicolon.

Supported values:

Property Description
orderStatistics Extra statistics data like totalQuantitySold and count of orders in states.
galleryItemsCount Count of public images in product detail.
ExampleorderStatistics;galleryItemsCount

Response schema

1 status code documented

200SuccessPaginated product feed response.
countnumberRequired

Number of items returned on this page. For the total number of items matching the filter across all pages use totalCount.

totalCountnumberRequired

Total number of products matching the filter (query + category), independent of page and limit. Use Math.ceil(totalCount / limit) to compute the page count.

itemsobject[]Required

List of product feed items.

Each array item:

Product feed item. Returned properties depend on the properties query parameter.

idnumberRequired

Internal product ID.

Example42
namestringRequired

Localized product name.

ExampleCheese Burger
slugstringRequired

URL-friendly product identifier.

Examplecheese-burger
shortDescriptionstringOptional

Short HTML description.

mainImageUrlstringOptional

URL of the main product image (original blob). Always present when the product has a main image. For sized rendering prefer mainImageThumbUrl (128 px) or mainImageCardUrl (480 px).

mainImageThumbUrlstring | nullOptional
One of 2:
Variant 1
string

Scout-generated 128×128 WebP thumbnail URL, or null while the variant hasn't been rendered yet (see § "When null" below).

Dimensions: 128×128 px, square, cover-cropped. Format: WebP q75. Byte range: ~4–14 KB per file.

Intended use: row-level thumbnails in lists, autocomplete dropdowns, chat message previews, notification cards, mobile grid cells (60–120 px). At this size no other variant is worth requesting.

When null: the source image has been uploaded but the scout worker on the Contabo VPS hasn't finished rendering this variant yet. Fall back to the LQIP blur alone (with an optional "processing" overlay for cells ≥ 80 px). The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return a non-null URL — usually within seconds for a fresh upload, longer under scout backlog.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.thumb-webp.webp
Variant 2
null
mainImageCardUrlstring | nullOptional
One of 2:
Variant 1
string

Scout-generated 480×480 WebP URL, or null while the variant hasn't been rendered yet.

Dimensions: 480×480 px, square, cover-cropped. Format: WebP q80. Byte range: ~15–45 KB per file.

Intended use: medium-sized product previews — product-detail sidebar (240–520 px), category grid tiles on mobile / small desktop, storefront cards, hover popovers, e-mail template thumbnails. The single most-used variant in typical e-shop UI.

When null: same story as thumbUrl — variant not yet rendered by scout. Prefer thumbUrl (if available) as a temporary substitute over the LQIP blur alone.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.card-webp.webp
Variant 2
null
mainCategoryobjectOptional

Product category reference.

slugstringRequired

URL-friendly category identifier.

Examplesmartphone
codestringRequired

Internal category code.

ExampleCAT-001
namestringRequired

Localized category name.

ExampleSmartphones
pricenumberRequired

Product price including VAT.

Example250
priceWithoutVatnumberOptional

Product price excluding VAT.

vatnumberOptional

VAT percentage rate.

positionnumberRequired

Display position for sorting.

Example1
activebooleanRequired

Whether the product is active.

soldOutbooleanRequired

Whether the product is sold out.

warehouseAllQuantitynumberOptional

Total available warehouse quantity.

warehouseLimitnumberOptional

Minimum warehouse quantity threshold.

customFieldsobjectOptional

Custom key-value fields.

eventobjectOptional

Calendar event linked to the product.

idstringRequired

Event code identifier.

startTimeDate | string | string | numberRequired

Event start date and time.

One of 4:
Variant 1
Date

Event start date and time.

Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
endTimeDate | string | string | numberRequired

Event end date and time.

One of 4:
Variant 1
Date

Event end date and time.

Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
isAllDaybooleanRequired

Whether the event spans the entire day.

isBlockingbooleanRequired

Whether the event blocks other bookings.

titlestringRequired

Event title.

descriptionstringOptional

Event description text.

agendastringOptional

Event agenda or schedule.

urlstringOptional

External URL for the event.

locationTitlestringOptional

Name of the event location.

orderStatisticsobjectOptional

Aggregated order statistics for the product.

totalQuantitySoldnumberRequired

Total quantity sold across all order statuses.

statusNewnumberRequired

Quantity in new orders.

statusProcessingnumberRequired

Quantity in processing orders.

statusStornonumberRequired

Quantity in canceled orders.

statusDonenumberRequired

Quantity in completed orders.

galleryItemsCountnumberOptional

Count of public images in product detail.

Response example

application/json
{
  "count": 0,
  "totalCount": 0,
  "items": [
    {
      "id": 42,
      "name": "Cheese Burger",
      "slug": "cheese-burger",
      "shortDescription": "example_shortDescription",
      "mainImageUrl": "example_mainImageUrl",
      "mainCategory": {
        "slug": "smartphone",
        "code": "CAT-001",
        "name": "Smartphones"
      },
      "price": 250,
      "priceWithoutVat": 0,
      "vat": 0,
      "position": 1,
      "active": false,
      "soldOut": false,
      "warehouseAllQuantity": 0,
      "warehouseLimit": 0,
      "customFields": {},
      "event": {
        "id": "example_id",
        "isAllDay": false,
        "isBlocking": false,
        "title": "example_title",
        "description": "example_description",
        "agenda": "example_agenda",
        "url": "example_url",
        "locationTitle": "example_locationTitle"
      },
      "orderStatistics": {
        "totalQuantitySold": 0,
        "statusNew": 0,
        "statusProcessing": 0,
        "statusStorno": 0,
        "statusDone": 0
      },
      "galleryItemsCount": 0
    }
  ]
}

Request example

GET /api/v1/product/feed

get
curl -X GET "https://api.bizkithub.com/api/v1/product/feed?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE&query=iphone&locale=cs&orderBy=position&category=smartphone&page=1&limit=32&properties=orderStatistics%3BgalleryItemsCount" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key