getPostAdmin BFF

/bff/post/list

Returns a paginated list of posts for the authenticated organisation. Default ordering: starred-first, archived-last, then newest published. Each post includes basic metadata, derived publication status, word count, reading time, main image URL, and associated tags.

PostgetBffPostList

Parameters

10 query

Query parameters

· 10

mainCategoryCodestringOptional

Filter posts by main category code. If not provided, all posts are returned.

Exampleexample_mainCategoryCode

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

status"draft" | "scheduled" | "published" | "private" | "archived"Optional

Filter by computed publication status (draft, scheduled, published, private, archived).

visibility"public" | "private" | "unlisted" | "subscribe"Optional

Filter by raw visibility column.

hasMainImagestringOptional

"true" to keep only posts with a main image, "false" to keep only those without.

Exampleexample_hasMainImage

missingTranslationstringOptional

"true" to keep only posts missing a translation in at least one of the org's configured locales.

Exampleexample_missingTranslation

tagCodestringOptional

Filter posts by tag code (organisation-scoped). Only posts carrying this tag are returned.

Exampleexample_tagCode

kind"post" | "branch" | "all"Optional

Discriminator filter. Default post — the admin blog grid never surfaces branch-owned documents. branch = only branch documents. all = every content record (diagnostic view).

orderBystringOptional

Sort spec <field>:<asc|desc>. Allowed fields: publishedDate, updatedDate, insertedDate, title, wordCount, commentsCount, viewsCount, ratingAverage.

ExamplepublishedDate:desc

sortBystringOptional

Alias for orderBy (legacy).

Exampleexample_sortBy

Response schema

1 status code documented

200SuccessPaginated list of posts with metadata.

itemsobject[]Required

Array of post items matching the query criteria.

Each array item:

Single post item in the list.

idstringRequired

Unique external identifier of the post (UUID format).

titlestringRequired

Post title, truncated to 140 characters for list view.

mainCategoryIdstringOptional

External ID of the main category this post belongs to.

mainCategoryNamestringOptional

Localized name of the main category.

mainAuthorIdstringOptional

External ID of the main author (customer/contact).

mainAuthorNamestringOptional

Full name of the main author.

commentsCountnumberRequired

Total number of comments on this post.

publishedDateDate | string | string | numberOptional

Date when the post was published. Null if not yet published.

One of 4:

Variant 1

Date

Date when the post was published. Null if not yet published.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

insertedDateDate | string | string | numberRequired

Date when the post was created in the system.

One of 4:

Variant 1

Date

Date when the post was created in the system.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

updatedDateDate | string | string | numberRequired

Date when content__post.* was last updated. Useful for an "edited recently" sort.

One of 4:

Variant 1

Date

Date when content__post.* was last updated. Useful for an "edited recently" sort.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

visibility"public" | "private" | "unlisted" | "subscribe"Required

Post visibility level. "public" = visible to everyone, "private" = visible only to author and admins, "unlisted" = accessible via direct link but not listed, "subscribe" = visible only to subscribers.

status"draft" | "scheduled" | "published" | "private" | "archived"Required

Computed publication status derived from (visibility, publishedDate, deletedDate). See resolvePostStatus in core for the precedence rules.

mainImageUrlstringOptional

URL of the main/featured image for the post.

isStarbooleanRequired

Whether the post is starred/featured. Starred posts appear first in the list.

isDeletedbooleanRequired

Whether the post has been soft-deleted.

wordCountnumberRequired

Approximate word count of the displayed locale's content (HTML stripped).

readingTimeMinutesnumberRequired

Approximate reading time in minutes (200 wpm). 0 when the post has no content.

hasPerexbooleanRequired

Whether the displayed locale has a non-empty perex (used by SEO health indicator).

tagsobject[]Required

Array of tags assigned to this post. Can be empty if no tags are assigned.

Each array item:

Tag associated with the post.

idnumberRequired

Unique identifier of the tag.

namestringRequired

Display name of the tag.

codestringRequired

URL-friendly code/slug of the tag.

colorstringOptional

Hex color code for the tag (e.g., "#FF5733").

translatedLocalesstring[]Required

Locales for which a translation exists in content__post_locale.

Locale code (e.g. "cs", "en").

staleLocalesstring[]Required

Subset of translatedLocales where the row's source_history_id no longer matches the newest source-locale history entry (or is NULL / legacy) — the source article has been edited since this translation was produced. Empty for up-to-date posts and for legacy posts without any source history to compare against.

Locale code that is out of date.

viewsCountnumberRequired

Cumulative number of times the post was served by /api/v1/post. Approximate; synced into content__post.views_count every 5 minutes.

viewsRecentDeltanumberOptional

Views gained in the last VIEWS_TREND_WINDOW_DAYS (currently 3, see selectPostList). Omitted when there is no view-count snapshot from that far back — usually a very fresh post or one whose views have always been zero. Never negative.

viewsPriorDeltanumberOptional

Views gained in the window immediately preceding viewsRecentDelta. Paired with viewsRecentDelta to render an up/down/flat trend indicator. Omitted when the older snapshot is missing (so the admin cell falls back to plain count).

ratingAveragenumberOptional

Average reader rating (1–5) from content__post_feedback. Omitted when the post has no feedback yet.

ratingCountnumberRequired

Number of reader feedback entries the rating average is based on.

itemCountnumberRequired

Total number of posts matching the query (before pagination). Useful for pagination controls.

Response example

application/json

{
  "items": [
    {
      "id": "example_id",
      "title": "example_title",
      "mainCategoryId": "example_mainCategoryId",
      "mainCategoryName": "example_mainCategoryName",
      "mainAuthorId": "example_mainAuthorId",
      "mainAuthorName": "example_mainAuthorName",
      "commentsCount": 0,
      "mainImageUrl": "example_mainImageUrl",
      "isStar": false,
      "isDeleted": false,
      "wordCount": 0,
      "readingTimeMinutes": 0,
      "hasPerex": false,
      "tags": [
        {
          "id": 0,
          "name": "example_name",
          "code": "example_code",
          "color": "example_color"
        }
      ],
      "translatedLocales": [
        "string"
      ],
      "staleLocales": [
        "string"
      ],
      "viewsCount": 0,
      "viewsRecentDelta": 0,
      "viewsPriorDelta": 0,
      "ratingAverage": 0,
      "ratingCount": 0
    }
  ],
  "itemCount": 0
}

Request example

GET /bff/post/list

get

curl -X GET "https://api.bizkithub.com/bff/post/list?mainCategoryCode=example_mainCategoryCode&locale=cs&hasMainImage=example_hasMainImage&missingTranslation=example_missingTranslation&tagCode=example_tagCode&orderBy=publishedDate%3Adesc&sortBy=example_sortBy" \
  -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