Initiate AI answer generation

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.

post/ai/search

Request

Base URL
https://public.stonly.com/api/v3
Auth
HTTP basic

Query parameters

teamIdinteger

ID of the team to manage. Optional if the API key is associated with a single team.

Request body

querystring 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

aiAgentIdinteger required

ID of Ai Agent defining configuration for a search

conversationIdSchema (unresolved $ref)

kbBaseUrlstring 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.

userEmailSchema (unresolved $ref)

webhookUrlSchema (unresolved $ref)

customerUserIdstring

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.

propertiesobject

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

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

questionAnswerIdstring uuid required

Unique identifier for the generated AI answer

Example response

{
  "questionAnswerId": "92c3c11c-5a2b-4814-a97d-cf2e0e5256a9"
}

Changes

No recorded changes to this operation across all 1 revision of this API.