BizKitHub
DocsAPI ReferencePost/api/v1/post/search
getPostPublic API v1

/api/v1/post/search

Full-text search across posts. Returns matching posts with highlighted title and snippet, relevance score, and optional "did you mean" suggestions. Results can be narrowed to a single category via mainCategory (resolved as a route slug in the requested locale) and sorted either by relevance (default) or by publication date via orderBy=date.

postgetApiV1PostSearch

Parameters

9 query

Query parameters

· 9
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
querystringRequired

Full-text search query entered by the client. Can contain words, phrases or year numbers, e.g. "2025".

Example2025
countrystringOptional

Optional ISO 3166-1 alpha-2 country code of the visitor (e.g. "CZ"). When set, the response is filtered to posts whose per-country / per-continent allowlist matches the visitor — a post targeted at continent "EU" matches every EU country, and a post with no rules stays globally available. When omitted, the filter is disabled and every post is returned regardless of geo settings. The API does NOT infer the country from the caller's IP; it is up to the caller to resolve and supply it. Case-insensitive. Unknown codes are rejected with HTTP 400 (PUBLIC_COUNTRY_CODE_UNKNOWN). The pseudo code INT selects the international (region-less) edition of a multi-region publication: only posts WITHOUT any country / continent rule.

Length: 2–3
ExampleCZ
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)

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
identityIdstringOptional

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

ExampleZ9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg
limitstring | integerOptional

Maximum number of items to return in items, ordered by relevance descending. When omitted, the server default of 100 is applied. Hard-capped at 200 regardless of a larger value being requested.

Range: 1–200
Example100
offsetstring | integerOptional

Number of ranked results to skip, for pagination ("load more"). Default 0. Honoured by the in-memory search used for organisations with a small post corpus; the large-corpus SQL search always starts at 0 (check offset in the response).

Range: 0–10000
Example0
mainCategorystringOptional

Optional main category route slug to restrict the search to posts assigned to that category. The slug is resolved in the requested locale against the organisation category routes; when it resolves to no category, the search returns zero results.

Examplenovinky
orderBy"relevance" | "date"Optional

Ordering of the returned items. Defaults to relevance (score descending, current behavior). date returns the most-recently-published matches first (published_date DESC NULLS LAST, then inserted_date DESC). The score field is still populated in both modes.

Examplerelevance

Response schema

1 status code documented

200Success
querystringRequired

Normalized form of the search query actually used by the search engine (e.g. trimmed and lower-cased).

Example2025
titlestringRequired

Human-readable version of the query intended for UI headings (typically first letter upper-cased).

Example2025
countResultsnumberRequired

Total number of matching posts found before the response-side truncation is applied. May be larger than items.length when the result set is capped by limit. Compare with truncated to know whether the client should suggest a more specific query.

Example1
limitnumberRequired

Effective maximum number of items included in this response. Echoes the limit query parameter (if provided and within 1–200), otherwise falls back to the server default of 100. The search returns at most this many entries in items, sorted by relevance descending.

Example100
truncatedbooleanRequired

True when countResults exceeds limit, i.e. some matching posts were dropped from the items array. Use as a hint to nudge the user to refine the query.

Examplefalse
durationMsnumberRequired

Server-side wall-clock time spent producing this response, in milliseconds. Covers the SQL search, tag/blob enrichment and scoring; excludes network transfer. Useful for "Found X results in Y ms" UI copy and for spotting slow queries.

Example42
didYouMeanstring | nullRequired
One of 2:
Variant 1
string

Optional alternative query suggestion when a likely typo or more relevant variant is detected. Null if no suggestion is available.

Example2024
Variant 2
null
offsetnumberOptional

Number of skipped results this page starts after.

Example0
autoCorrectedbooleanOptional

True when the query as typed matched nothing and the results are for didYouMean instead (show "Showing results for …"). False / absent: didYouMean, if set, is only a suggestion.

Exampletrue
crossLocalebooleanOptional

True when nothing matched in the requested locale and the hits were found in another locale. Items are still returned in the requested locale when a translation exists (see items[].locale).

Examplefalse
partialbooleanOptional

True when no post contains every query word and the items match only some of them.

Examplefalse
facetsobject[]Optional

Main categories of all matching posts with counts, computed before the mainCategory filter, for a "filter by category" UI. In-memory search only.

Each array item:
slugstringRequired

Category route slug (use as mainCategory).

Examplesales
namestringRequired

Category name in the requested locale.

ExampleSales
countnumberRequired

Number of matching posts whose main category this is.

Example4
itemsobject[]Required

List of search results for the given query, ordered by relevance (highest score first). Limited to a maximum of 100 items.

Each array item:
slugstringRequired

Canonical URL slug of the matched post in the requested locale. Append to your site base URL to create a link.

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

Plain-text title of the post, normalized for search but without HTML highlighting.

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

Plain-text excerpt from the post content around the matched query, shortened for use in the search results list.

Exampleproto vznikla soutěž KYBER CENA ROKU: aby ukázala lidi a projekty, kteří dělají Českou republiku bezpečnější. Třetí ročník vyhlášení proběhl 9. října 2025 na slavnostním galavečeru za účasti odborné poroty, partnerů a finalistů ze školství, státní správy, průmyslu i komerční bezpečnosti. Letos šlo m
titleHighlightedstringRequired

Post title with all occurrences of the query wrapped in a <strong> tag with inline highlight styles. Contains HTML and should be rendered as HTML, not escaped.

ExampleKYBER CENA ROKU <strong style="color:#003F99;background:#CCE0FF">2025</strong>: největší večer české kyberbezpečnosti letošního roku.
snippetHighlightedstringRequired

Content snippet with matched query terms highlighted using a <strong> tag with inline styles. Contains HTML and should be rendered as HTML, not escaped.

Exampleproto vznikla soutěž KYBER CENA ROKU: aby ukázala lidi a projekty, kteří dělají Českou republiku bezpečnější. Třetí ročník vyhlášení proběhl 9. října <strong style="color:#003F99;background:#CCE0FF">2025</strong> na slavnostním galavečeru za účasti odborné poroty, partnerů a finalistů ze školství, státní správy, průmyslu i komerční bezpečnosti. Letos šlo m
mainImageUrlstringOptional
Examplehttps://storage.xhp.cz/...
tagsobject[]Required

Array of tags assigned to this post. Only active tags are included.

Each array item:

Tag associated with the post.

slugstringRequired

URL-friendly code/slug of the tag.

Examplebezpecnost
namestringRequired

Human-readable display name of the tag.

ExampleBezpečnost
colorstringOptional

Hex color code for the tag.

Example#3B82F6
localestringOptional

Locale of slug (differs from the request on cross-locale hits).

Exampleen
perexstringOptional

Plain-text perex of the post.

publishedDatestringOptional

ISO publication date.

Example2026-07-26T10:00:00.000Z
categoryobjectOptional

Main category of the post.

slugstringRequired
Examplevouchers
namestringRequired
ExampleVouchers
sectionobjectOptional

Section of the post where the query words occur; snippet is cut from it. Absent when the post as a whole is the answer.

idstringRequired

Heading anchor id; link to /{slug}#{id}.

Examplevalidity
titlestringRequired
ExampleValidity
titleHighlightedstringRequired

Heading with highlight markup. Render as HTML.

scorenumberRequired

Relative relevance score computed from the text match and year-based boosting. Higher values indicate more relevant results and are used to sort items in descending order. The absolute range is not fixed and should be treated as an internal ranking hint.

Example195
categoriesobject[]Required

Active categories whose name in the requested locale contains every word of the query (max 5, exact and prefix matches first). Always empty when mainCategory is set.

Each array item:
idstringRequired

Category external id (16 chars).

Examplea1b2c3d4e5f6g7h8
slugstringRequired

Canonical category route slug in the requested locale.

Exampleairlines
namestringRequired

Category name in the requested locale.

ExampleAirlines
nameHighlightedstringRequired

Category name with <strong> markup around the matched words. Render as HTML.

Example<strong>Air</strong>lines

Response example

application/json
{
  "query": "2025",
  "title": "2025",
  "countResults": 1,
  "limit": 100,
  "truncated": false,
  "durationMs": 42,
  "offset": 0,
  "autoCorrected": true,
  "crossLocale": false,
  "partial": false,
  "facets": [
    {
      "slug": "sales",
      "name": "Sales",
      "count": 4
    }
  ],
  "items": [
    {
      "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.",
      "snippet": "proto vznikla soutěž KYBER CENA ROKU: aby ukázala lidi a projekty, kteří dělají Českou republiku bezpečnější. Třetí ročník vyhlášení proběhl 9. října 2025 na slavnostním galavečeru za účasti odborné poroty, partnerů a finalistů ze školství, státní správy, průmyslu i komerční bezpečnosti. Letos šlo m",
      "titleHighlighted": "KYBER CENA ROKU <strong style=\"color:#003F99;background:#CCE0FF\">2025</strong>: největší večer české kyberbezpečnosti letošního roku.",
      "snippetHighlighted": "proto vznikla soutěž KYBER CENA ROKU: aby ukázala lidi a projekty, kteří dělají Českou republiku bezpečnější. Třetí ročník vyhlášení proběhl 9. října <strong style=\"color:#003F99;background:#CCE0FF\">2025</strong> na slavnostním galavečeru za účasti odborné poroty, partnerů a finalistů ze školství, státní správy, průmyslu i komerční bezpečnosti. Letos šlo m",
      "mainImageUrl": "https://storage.xhp.cz/...",
      "tags": [
        {
          "slug": "bezpecnost",
          "name": "Bezpečnost",
          "color": "#3B82F6"
        }
      ],
      "locale": "en",
      "perex": "example_perex",
      "publishedDate": "2026-07-26T10:00:00.000Z",
      "category": {
        "slug": "vouchers",
        "name": "Vouchers"
      },
      "section": {
        "id": "validity",
        "title": "Validity",
        "titleHighlighted": "example_titleHighlighted"
      },
      "score": 195
    }
  ],
  "categories": [
    {
      "id": "a1b2c3d4e5f6g7h8",
      "slug": "airlines",
      "name": "Airlines",
      "nameHighlighted": "<strong>Air</strong>lines"
    }
  ]
}

Request example

GET /api/v1/post/search

get
curl -X GET "https://api.bizkithub.com/api/v1/post/search?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE&query=2025&country=CZ&locale=cs&identityId=Z9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg&limit=100&offset=0&mainCategory=novinky&orderBy=relevance" \
  -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