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

7 query

Query parameters

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

Response example

application/json
{
  "query": "2025",
  "title": "2025",
  "countResults": 1,
  "limit": 100,
  "truncated": false,
  "durationMs": 42,
  "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"
        }
      ],
      "score": 195
    }
  ]
}

Request example

GET /api/v1/post/search

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