Docs API Reference Post/api/v1/post/feed

getPostPublic API v1

/api/v1/post/feed

Returns a feed of the most recent posts. Posts are filtered by the requested locale and ordered by their last modification date. The limit parameter controls how many items are returned, and the optional fields parameter lets you request additional properties (for example content). When requested, the content field is returned as a sanitized, single-line teaser truncated to a fixed length suitable for listing views. You can filter posts by tag (using tag code) or by main category (using category route slug).

Pagination: use limit together with offset to page through results. The response always carries a top-level total (count of items matching the same WHERE) and hasMore (offset + items.length < total) so paginators do not need a second call to know when to stop.

Ordering: orderBy accepts a whitelisted set of values (updatedDate:desc — default, publishedDate:desc, publishedDate:asc, views:desc, commentCount:desc, title:asc, title:desc). Starred/pinned posts are always kept at the top regardless of the selected ordering.

Extra opt-in fields: fields accepts content, routes, author, views, perex, readingTime, fallbackImage.

Locale fallback: locale is optional. When omitted or resolved to an unsupported value, the organisation's primary locale is used automatically.

postgetApiV1PostFeed

Parameters

10 query

Query parameters

· 10

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

localestringOptional

Communication locale code — controls the language of textual data (product names, descriptions, articles, storefront UI, transactional e-mails).

Preferred format: BCP 47 language tag — language[-Script][-REGION]. Use the full tag whenever the script or region matters:

en-GB vs. en-US (British vs. American spelling)
pt-PT vs. pt-BR (European vs. Brazilian Portuguese)
zh-Hans vs. zh-Hant (Simplified vs. Traditional Chinese)
sr-Latn vs. sr-Cyrl (Latin vs. Cyrillic Serbian)

Backwards-compatible fallback: the bare two-letter ISO 639-1 code (cs, en, pl, …) is accepted indefinitely — legacy clients that only send the language subtag continue to work unchanged.

Resolution algorithm (server-side): the input is resolved against the supported locale list via the [RFC 4647 Lookup] progressive-fallback strategy — trailing subtags are stripped one by one until a supported locale is found. Example: en-GB-oxendict → en-GB → en (matched). If no subtag combination is supported, the request is rejected.

Currently supported locales: cs, en, fr, it, pl, de, sk, sv, es, zh, ja, uk, da, hu, ro, nl, pt, fi, nb, hr. Region-specific variants (e.g. en-GB, pt-BR) are accepted and resolved to their base language when the exact variant is not registered separately.

Length: 2–35

Examplecs

fieldsstringOptional

Comma-separated list of additional fields to include in the response. Supported values: content (adds a sanitized single-line teaser), routes (adds the cross-locale canonical routes for hreflang / sitemap use), author (adds { name, profileSlug } for the post main author), views (adds cumulative viewsCount), perex (adds the localized perex; empty string when not authored), readingTime (adds readingTimeMinutes computed from the post HTML at ~200 wpm, always >= 1), fallbackImage (adds fallbackImageUrl: the first <img src> in the body, only when the post has no main image). Example: content,routes,author.

Examplecontent

limitnumberOptional

Maximum number of items to return. If omitted, a default internal limit is applied.

Example64

offsetnumberOptional

Zero-based offset for pagination. Skips the first offset items after the WHERE / ORDER BY are applied. Combine with limit to page through results; use the top-level total / hasMore in the response to know when to stop.

Range: 0–∞

Example0

identityIdstringOptional

Logged user identity (from your frontend cookies). Learn more

ExampleZ9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg

tagstringOptional

Optional tag code to filter posts. Only posts that have this tag assigned will be returned. The tag must be active and belong to the same organisation.

Examplenovinky

mainCategorystringOptional

Optional main category route slug to filter posts. Only posts that have this category set as their main category will be returned.

Examplenovinky

onlyStarredbooleanOptional

Filter to only pinned/starred posts (typically the homepage hero slot).

Exampletrue

Ordering of the returned list. Defaults to updatedDate:desc (current behavior). The implicit is_star DESC prefix is preserved for every ordering so pinned posts stay at the top.

ExamplepublishedDate:desc

Response schema

1 status code documented

200Success

itemsobject[]Required

Each array item:

idstringRequired

Post public id (content__post.external_id, 16-char string). Stable across renames.

Example6IU2SWgP76FO2UXw

slugstringRequired

Unique URL-friendly identifier of the article. Used to construct the public route.

Examplekyber-cena-roku-2025-nejvetsi-vecer-ceske-kyberbezpecnosti-letos

titlestringRequired

Human-readable article title. Returned in the language specified in the locale parameter.

ExampleKYBER CENA ROKU 2025: největší večer české kyberbezpečnosti letošního roku.

mainImageUrlstringOptional

URL of the main/featured image for the post. Null if no main image is set.

Examplehttps://storage.xhp.cz/...

last_modification_dateDate | string | string | numberRequired

Timestamp of the last modification of the article. ISO 8601 format.

One of 4:

Variant 1

Date

Timestamp of the last modification of the article. ISO 8601 format.

Example2025-11-05T15:54:44.280Z

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

publishedDateDate | string | string | number | nullRequired

One of 2:

Variant 1

Date | string | string | number

First-published timestamp of the article. Null for older posts that never had a publish date recorded.

One of 4:

Variant 1

Date

First-published timestamp of the article. Null for older posts that never had a publish date recorded.

Example2025-11-05T15:54:44.280Z

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

Variant 2

null

commentCountnumberRequired

Number of comments associated with the article.

Example12

isStarbooleanOptional

True if the post is starred/pinned. Omitted when false.

contentstringOptional

Full article content in plain text or HTML. Returned only if the field is explicitly requested via the fields query parameter.

ExampleŽijeme ve světě, kde je normální...

perexstringOptional

Localized perex (short lead paragraph). Present only when fields includes perex. Empty string when the author did not fill in a perex for this locale.

ExampleKrátký úvodní odstavec článku…

viewsCountnumberOptional

Cumulative public read count from /api/v1/post (buffered + flushed by cron). Present only when fields includes views.

Example1240

readingTimeMinutesnumberOptional

Estimated reading time in whole minutes at ~200 words per minute. Computed on the fly from the post HTML. Always at least 1, even for very short posts (matches the Medium convention). Present only when fields includes readingTime.

Examples1312

fallbackImageUrlstring | nullOptional

One of 2:

Variant 1

string

URL of the first <img> found in the post body. Present only when fields includes fallbackImage. null when the post already has a mainImageUrl (no fallback needed) or when the body contains no image. Relative paths are returned as-is; the caller is responsible for resolving them against a base URL.

Examplehttps://cdn.example.com/inline-hero.jpg

Variant 2

null

authorobjectOptional

Main author of the post. Present only when fields includes author. Falls back to { name: "", profileSlug: "" } when the author record is missing or filtered out by the organisation scope.

namestringRequired

Human-readable author display name (first + last name).

ExampleJan Barášek

profileSlugstringRequired

Author profile slug — shop__contact.external_id of the main author.

Exampleabcdef0123456789

mainCategoryobjectOptional

Main category of the post. Null if no main category is assigned or if the category has no route/locale data for the requested locale.

slugstringRequired

URL-friendly slug of the main category route in the requested locale. Use this to construct links to the category page.

Examplenovinky

titlestringRequired

Localized display name of the main category.

ExampleNovinky

tagListobject[]Required

Array of tags assigned to this post. Empty array if no tags are assigned. Only active tags are included.

Each array item:

Tag associated with the post.

slugstringRequired

URL-friendly code/slug of the tag. Can be used to filter posts by tag.

Examplebezpecnost

namestringRequired

Human-readable display name of the tag.

ExampleBezpečnost

colorstringOptional

Hex color code for the tag (e.g., "#FF5733"). Null if no color is set.

Example#3B82F6

routesobject[]Optional

Canonical routes for every locale this post is translated into. Present only when fields includes routes. Use it to build sitemap alternates / hreflang links without calling /post per item.

Each array item:

slugstringRequired

Canonical URL-friendly slug of the post in the given locale.

Examplekyber-cena-roku-2025

localestringRequired

Communication locale code — controls the language of textual data (product names, descriptions, articles, storefront UI, transactional e-mails).

Preferred format: BCP 47 language tag — language[-Script][-REGION]. Use the full tag whenever the script or region matters:

en-GB vs. en-US (British vs. American spelling)
pt-PT vs. pt-BR (European vs. Brazilian Portuguese)
zh-Hans vs. zh-Hant (Simplified vs. Traditional Chinese)
sr-Latn vs. sr-Cyrl (Latin vs. Cyrillic Serbian)

Length: 2–35

Examplescsenen-GBpt-BRzh-Hans

totalnumberRequired

Total number of posts matching the same WHERE (locale, tag, mainCategory, onlyStarred, visibility). Independent of limit / offset — use it to render paginators.

Example428

hasMorebooleanRequired

True when there are more items beyond the current page — computed as offset + items.length < total.

Examplestruefalse

Response example

application/json

{
  "items": [
    {
      "id": "6IU2SWgP76FO2UXw",
      "slug": "kyber-cena-roku-2025-nejvetsi-vecer-ceske-kyberbezpecnosti-letos",
      "title": "KYBER CENA ROKU 2025: největší večer české kyberbezpečnosti letošního roku.",
      "mainImageUrl": "https://storage.xhp.cz/...",
      "last_modification_date": "2025-11-05T15:54:44.280Z",
      "commentCount": 12,
      "isStar": false,
      "content": "Žijeme ve světě, kde je normální...",
      "perex": "Krátký úvodní odstavec článku…",
      "viewsCount": 1240,
      "readingTimeMinutes": 1,
      "author": {
        "name": "Jan Barášek",
        "profileSlug": "abcdef0123456789"
      },
      "mainCategory": {
        "slug": "novinky",
        "title": "Novinky"
      },
      "tagList": [
        {
          "slug": "bezpecnost",
          "name": "Bezpečnost",
          "color": "#3B82F6"
        }
      ],
      "routes": [
        {
          "slug": "kyber-cena-roku-2025",
          "locale": "cs"
        }
      ]
    }
  ],
  "total": 428,
  "hasMore": true
}

Request example

GET /api/v1/post/feed

get

curl -X GET "https://api.bizkithub.com/api/v1/post/feed?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE&locale=cs&fields=content&limit=64&offset=0&identityId=Z9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg&tag=novinky&mainCategory=novinky&onlyStarred=true&orderBy=publishedDate%3Adesc" \
  -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