---
kind: rest
area: chatbot
tier: free
summary: The routes the chat widget and the search answer call to send a message, read and reset the conversation and rate an answer.
---

# Chatbot REST routes

The routes live under `/wp-json/kimaai/v1/`. A call from a logged-in browser sends the WordPress REST nonce, as every WordPress REST call does; a script uses an application password. A route that names a feature is registered only while that feature is not hidden (`app/Features/Features.php`).

Each route says its access. Internal: the route serves KimaAI's own admin screens or chat widget and may change or go away in any release without notice, so code outside KimaAI should not call it. Public: the route keeps its path, its arguments and its answer across releases, and changes only after a deprecation.

The chat widget, the inline chat, the Ask AI button and the search answer box call these routes. They are open to anyone, like the page the visitor reads: a visitor's conversation is the session in the `kimaai_chatbot_session_id` cookie, and a conversation that belongs to a logged-in user is refused to anyone else (403).

## POST /kimaai/v1/chatbot

- Access: internal
- Permission: anyone; the conversation is the visitor's session, and one that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: none

Sends the visitor's message to the AI provider and answers it, with the chatbot's settings, its knowledge and its tools. The request passes the chatbot's gate, rate limit and daily limit first. With `stream` true and an `Accept: text/event-stream` header, and streaming switched on in the chatbot settings, the answer arrives as server-sent events (`delta`, `tool`, `done`, `error`).

| Argument          | Type    | Required | Description                                                                             |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `message`         | string  | yes      | The visitor's message.                                                                  |
| `postId`          | integer | no       | The post the chat runs on, for answers about the page. Default `0`.                     |
| `section`         | string  | no       | The section of the page the visitor asks about.                                         |
| `command`         | object  | no       | A quick action or button of the widget instead of a typed message.                      |
| `scope`           | object  | no       | Taxonomy and term slugs that limit the knowledge search (KimaAI Pro).                   |
| `stream`          | boolean | no       | True to stream the answer.                                                              |
| `renders_sources` | boolean | no       | True when the client shows the sources itself; the answer then carries no source links. |
| `lang`            | string  | no       | The language of the page, for multilingual sites.                                       |
| `sessionId`       | string  | no       | The session to continue; the cookie's session otherwise.                                |

Returns: Without streaming: the answer (`message`, `sessionId`, `history`, and `renderables` and `sources` when there are any). An `error` with 400 (also when the daily or rate limit is reached), 403 (blocked by the gate, or another account's conversation), or the AI provider's error with its status.

## GET /kimaai/v1/chatbot/history

- Access: internal
- Permission: anyone; a conversation that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: none

Reads a conversation. Reading never starts a session: without one the answer is empty.

| Argument     | Type   | Required | Description                                       |
| ------------ | ------ | -------- | ------------------------------------------------- |
| `session_id` | string | no       | The conversation; the cookie's session otherwise. |

Returns: `sessionId`, `messages`, `feedback` (`csatGiven`, `ratedMessageIds`) and `quickActions`.

## POST /kimaai/v1/chatbot/history/clear

- Access: internal
- Permission: anyone
- Tier: free
- Feature: none

Starts a new conversation: the session cookie gets a new ID. The stored conversation is kept.

No arguments.

Returns: `ok` and the new `sessionId`, empty when the visitor had no session.

## POST /kimaai/v1/chatbot/feedback/message

- Access: internal
- Permission: anyone; the conversation must exist, and one that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: none

Stores a thumbs up or down for one answer. An answer is rated once (409 after that).

| Argument     | Type    | Required | Description                        |
| ------------ | ------- | -------- | ---------------------------------- |
| `session_id` | string  | yes      | The conversation.                  |
| `message_id` | string  | yes      | The answer that is rated.          |
| `rating`     | integer | yes      | 1 for helpful, -1 for not helpful. |
| `comment`    | string  | no       | A comment, plain text.             |

Returns: `ok` and the `id` of the rating; 400, 403, 404 or 409 with an `error`.

## POST /kimaai/v1/chatbot/feedback/csat

- Access: internal
- Permission: anyone; the conversation must exist, and one that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: none

Stores the visitor's satisfaction rating (CSAT) for a conversation, once per conversation.

| Argument     | Type    | Required | Description            |
| ------------ | ------- | -------- | ---------------------- |
| `session_id` | string  | yes      | The conversation.      |
| `rating`     | integer | yes      | 1 to 5 stars.          |
| `comment`    | string  | no       | A comment, plain text. |

Returns: `ok` and the `id` of the rating; 400, 403, 404 or 409 with an `error`.

## POST /kimaai/v1/answer

- Access: internal
- Permission: anyone
- Tier: free
- Feature: search-answer

Answers a search query for the search answer box, in a session of its own. Without a vector database the answer is grounded in the search results the box rendered, which the page signs into `grounding`; with one (KimaAI Pro) the knowledge search finds them. Answers are cached per query, language, scope, results and the visitor's access.

| Argument    | Type    | Required | Description                                                           |
| ----------- | ------- | -------- | --------------------------------------------------------------------- |
| `query`     | string  | yes      | The search query.                                                     |
| `lang`      | string  | no       | The language of the page.                                             |
| `scope`     | object  | no       | Taxonomy and term slugs that limit the knowledge search (KimaAI Pro). |
| `stream`    | boolean | no       | True to stream the answer as server-sent events.                      |
| `grounding` | string  | no       | The signed search results the box shows.                              |

Returns: `message`, `sources`, `sessionId`, `messageId` and `cached` (true when the answer came from the cache); 400 when there are no search results to answer from, 403 when the gate blocks the query.
