---
title: "Initiate AI answer generation"
method: POST
path: "/ai/search"
tags: ["ai"]
---

# Initiate AI answer generation

`POST /ai/search`

## Request

- Base URL: `https://public.stonly.com/api/v3`
- URL: `https://public.stonly.com/api/v3/ai/search`
- Auth: HTTP basic

Submits a natural language query to the AI engine. Returns a `questionAnswerId` used to poll for the result.

**Content targeting.** When `kbBaseUrl` points to a knowledge base in your team, that knowledge base's content-targeting rules apply to the answer, just as they do for a visitor browsing it. Guides and folders whose rules the end user doesn't meet are left out of retrieval, citations and guided answers, and a guide inside an excluded folder is excluded too. Only that knowledge base's rules apply: content the AI agent takes from other sources is not filtered. If `kbBaseUrl` doesn't match a knowledge base in your team, no targeting is applied.

Identify the end user with `customerUserId`, `properties`, or both. For an identified user, rules on standard properties (country, device, browser, language) use the values stored from their widget sessions. If you send neither, the end user is treated as an anonymous visitor and targeted guides and folders are hidden. Each request is evaluated on its own, so send the same identity on every turn of a conversation.

## Query parameters

- `teamId` integer

## Request body

- RequestSearch
  - `query` string, required: Query for which an answer is to be generated
  - `language` 'en' | 'en-US' | 'en-GB' | 'fr' | 'fr-BE' | 'fr-CA' | 'de' | 'nl' | 'nl-BE' | 'es' | 'it' | 'pt' | 'pt-BR' | 'pl' | 'sv' | 'no' | 'nb' | 'nn' | 'fi' | 'hi' | 'bn' | 'mr' | 'te' | 'ta' | 'ko' | 'ja' | 'tr' | 'ca' | 'th', required: Language code used for the AI search query. Supported values map as follows: | Code | Language | |---|---| | `en` | English | | `en-US` | English (United States) | | `en-GB` | English (United Kingdom) | | `fr` | French | | `fr-BE` | French (Belgium) | | `fr-CA` | French (Canada) | | `de` | German | | `nl` | Dutch | | `nl-BE` | Flemish | | `es` | Spanish | | `it` | Italian | | `pt` | Portuguese | | `pt-BR` | Portuguese (Brazil) | | `pl` | Polish | | `sv` | Swedish | | `no` | Norwegian | | `nb` | Norwegian Bokmål | | `nn` | Norwegian Nynorsk | | `fi` | Finnish | | `hi` | Hindi | | `bn` | Bengali | | `mr` | Marathi | | `te` | Telugu | | `ta` | Tamil | | `ko` | Korean | | `ja` | Japanese | | `tr` | Turkish | | `ca` | Catalan | | `th` | Thai |
  - `aiAgentId` integer, required: ID of Ai Agent defining configuration for a search
  - `conversationId` Schema (unresolved $ref)
  - `kbBaseUrl` string, uri: Optional base URL for the knowledge base. If provided, this value will be prepended to KB links generated in the response. It also selects the knowledge base whose content-targeting rules apply to the answer (see the operation description). Both custom domains and `<name>.stonly.com` addresses are recognised.
  - `userEmail` Schema (unresolved $ref)
  - `webhookUrl` Schema (unresolved $ref)
  - `customerUserId` string: ID of the end user asking the question: the same value you pass to the Stonly widget `identify` call. Content targeting for the knowledge base set in `kbBaseUrl` is then evaluated for this user. If that knowledge base has targeting rules, the user's stored properties are loaded, and any `properties` you send take precedence and are saved to the user. An ID Stonly hasn't seen before is treated as a user with no stored properties.
  - `properties` object: Custom properties of the end user, used for content targeting. They follow the same rules as the widget `identify` call: - A key must be 1 to 100 characters long as sent, a nested key counting as `parent.child`. An empty or longer key returns `400`. - Keys are then lowercased, and characters other than letters, digits, `-`, `.` and `|` are removed. - One level of nesting is allowed. Nested objects are flattened to dot-separated keys. Arrays and `null` values return `400`. - A value that doesn't match the property's configured format is ignored for targeting, and the request still returns `200`. - Properties your team hasn't defined yet are created when the knowledge base has targeting rules. Without `customerUserId`, the values apply to this request only and are not saved to any user. New properties are still created.

## Response `200`

Successful search request. Returns a questionAnswerId that can be used to poll for results.

- object
  - `questionAnswerId` string, uuid, required: Unique identifier for the generated AI answer

## Other responses

- `default`: Standard error response.

---

[API](https://skmtc.dev/stonly/apis/stonly-public-api.md) - [All operations](https://skmtc.dev/stonly/apis/stonly-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stonly/apis/stonly-public-api/revisions/4ba5b03a634a?raw)