Search API
Open in CMSThe Knowledge Search API screen lets your own systems search this agent's knowledge with an API key and get the matching chunks back, with no AI-generated answer. Found in the agent sidebar under Channels → Search API. It works for service agents only; on a personal agent a notice explains this and the controls stay off.
The page has three tabs: Access, Permissions, and Log. The switch and the keys apply at once. The Permissions and Log tabs each have a small form saved with the Save all changes bar at the bottom; switching tab with unsaved changes asks first.
Access tab
| Allow search through the API | Off by default. When off, every search is refused, even with a valid key. The hint shows when it was last changed. While it is on without an active key, a notice asks you to create one. |
| Endpoint | The address your system POSTs a query to, with a copy button. |
| Agent ID | The agent's ID, with a copy button. |
| cURL | A ready-to-run example request. It reads the key from the QLAR_SEARCH_KEY environment variable. |
| Keep the key on your server | A warning: whoever holds the key can send any permission code, so call the API only from your own back end. |
| API docs | Opens Knowledge Search API in a new tab. |
| Cost | Each search costs 1 credit, also when it finds nothing. Free when your organization's own embedding model serves the search. Refused requests cost nothing. |
Primary and Secondary keys
Two slots, so you can rotate keys without downtime. Each slot shows a status chip: Active, Expired, Revoked, or Empty.
| Name, Key, Created, Expires | The key's name, its last four characters (qks_…abcd), when it was made, and when it expires (or Never). |
| Create key / Replace key | Opens a dialog with Name (up to 80 characters) and Expiry (7, 14, 30, 90, 180, or 365 days, or Never expires; default 90 days). Replacing an active key warns that the old key stops working right away. |
| Copy your new key | Shown once after a key is made. Copy it before you close: the key cannot be shown again. Closing asks first. |
| Revoke | Asks for confirmation, then stops the key at once. A revoked key cannot be turned back on. |
Used by other agents
Shown when other agents search this one through Knowledge → External. One row per key Qlar made for them: Agent, Key (last four characters), Made, Status (Active or Revoked). The row menu has Revoke, which asks first and stops that agent's searches at once. See External Knowledge.
Permissions tab
| How permissions work in a search | An info notice: every search carries the codes picked here, and the caller's own codes are added on top. |
| Permission codes | Pick codes from the agent's permission list. They are added to every search made with this agent's keys. Leave it empty to use only the caller's codes. |
| No permission codes yet | Shown when the agent has no permission codes. Open Permissions goes to Users → Permissions. |
| Codes no longer in the list | A warning when a saved code was removed from the agent's permission list. |
Log tab
Log settings
| Keep entries for | How long entries are kept. When you shorten it, a warning says older entries are deleted, and saving asks for confirmation. A longer period applies to new entries only. |
| Store query text | On by default: the log keeps the query text. Off: the log keeps everything about a call except what was searched for, and shows Not stored. |
Search calls
Filters: From and To dates, and Outcome (All, Success, Failed). Refresh reloads the list; Load more shows older entries.
| Column | What it shows |
|---|---|
| Time | When the call was made, in your time zone. |
| Outcome | A Success or Failed chip. |
| Status | The HTTP status code returned. |
| Key | The key's name and last four characters. |
| Query | The query, or Not stored. |
| Results | How many chunks came back. |
| Credits | Credits charged (0 or 1). |
| Model | Qlar or Your model: whose embedding served the search. |
| Duration | How long the search took. |
| Error | The error code and message of a failed call. |
Click a row to open it: the chunks returned (nearest first), the nearest distance, the permissions the caller sent, the permissions the search used, the limit, and the caller's IP address and user agent.
Related guide: Knowledge Search API