Filter the documentation index by q
Query the documentation index with `locale` and `q` to find articles whose content contains a specific string. The API returns sections and summaries, not the full detail or match excerpts.
In this article
Use this guide when support, documentation or onboarding need to quickly check that there are articles related to a term such as `bookings` or `pos` without opening every article.
The filter runs on the backend only for the exact index routes `/api/public/docs` and `/api/app/docs`. The visible search on the Docs screen is a local interface filter over summaries that are already loaded.
Before you start
- The documentation bundle is published at `backend/docs-content/articles.json` or `DOCS_CONTENT_PATH` points to a valid `articles.json`.
- The query is made on the index route, with no section, article or `assets` in the path.
- The request uses `GET`; `HEAD` only serves as a technical check and does not evaluate `q`.
- For `/api/app/docs`, the operator has a valid Bearer token or `access_token` cookie. `/api/public/docs` does not require a session.
Instructions
- 1.
Choose the API prefix
Use `GET /api/public/docs` to validate the public index without a session, or `GET /api/app/docs` to check the same contract from an authenticated session. The operational difference is authentication; the `q` filter is shared.
- 2.
Send `locale` and `q`
Add the language and the term in the query string, for example `GET /api/public/docs?locale=en&q=bookings` or `GET /api/app/docs?locale=en&q=pos`. The backend trims whitespace from `q` and compares case-insensitively.
- 3.
Review the filtered index
Check `query`, `article_count` and `sections`. Each section groups matching articles by category and each article is returned as a summary with identifiers, title, summary, icon and media flag.
- 4.
Interpret the matches
An article can appear even if the term is not visible in the summary, because the search also evaluates metadata, intro, prerequisites, steps, validations and result of the full article.
- 5.
Keep it apart from the visible search
Do not document the visible search box on `/docs` as a backend call with `q` in the current normal flow. The public wiki and the Docs screen load the index and filter the received summaries locally.
Validations and limits
- If `q` is missing or becomes empty after trimming, the API returns the full index for the `locale`.
- If there are no matches, the response is still `200 OK` with `article_count: 0` and `sections: []`.
- The search is a lowercase substring match: it is not fuzzy, does not tokenise, does not stem and does not strip accents.
- `q` does not filter detail or asset routes; it only affects the exact index.
- The order of sections and articles follows the `articles.json` bundle; there is no relevance ranking.
- `theme` can travel as a general option, but it does not affect filtering and does not appear in the index response.
Expected result
The operator gets an index reduced to the requested language and the `q` term, with sections and summaries that are safe for reviewing documentation without exposing the full body of the articles.