Documentation > AI API: Vectors, Images & LLM

AI API - Your site chat bot in one call (assistant_chat)

AI API: Vectors, Images & LLM

The out-of-the-box chat bot of your site, in one call: you send the conversation, Opensolr searches your index, looks up the facts it needs, and streams back the answer with the links of its sources.

Endpointhttps://api.opensolr.com/solr_manager/api/assistant_chat
MethodPOST, a JSON body only (Content-Type: application/json)
Authemail and api_key in the JSON body: Authentication

01 · Body

index_nameRequired

The index of your site. Its owner's AI allowance is used.

messagesRequired

The conversation: up to 21 messages, roles user and assistant, text only, the last one from the user. The last question is at most 4000 characters.

instructionsOptional

Your own instructions to the chat bot, up to 4000 characters.

timezoneOptional

Your time zone, such as Europe/Paris, so that today and dates are right. Default UTC.

visitor_ipOptional

The public address of your visitor. One visitor gets at most 100 questions an hour on one index. It also answers questions about where the visitor is.

02 · Example

curl -sN -X POST "https://api.opensolr.com/solr_manager/api/assistant_chat" \
  -H "Content-Type: application/json" \
  -d '{"email": "YOUR_EMAIL", "api_key": "YOUR_API_KEY", "index_name": "my_index",
       "timezone": "Europe/Paris",
       "messages": [{"role": "user", "content": "Do you have a blue chair under 200 euros?"}]}'

03 · Answer

A stream of Server-Sent Events, one JSON per data: line:

data: {"type":"status","stage":"reading"}

data: {"type":"tool","name":"opensolr_site_search","args":{"query":"blue chair"}}

data: {"type":"text","text":"Yes: the [Blue chair](https://www.example.com/products/blue-chair) costs..."}

data: {"type":"done"}
status

What the chat bot is doing.

tool

A search or a lookup it runs, with its arguments.

text

A piece of the answer, as it is written, in Markdown with links.

done

The answer is complete.

error

It stopped: msg says why, for example ERROR_NO_ANSWER or ERROR_ASSISTANT_TIMEOUT after 60 seconds.

It searches your index by meaning, by exact words and by date, reads documents and pictures of your site, and looks up places, times, rates, VAT, distances, postal codes and IP locations: What the chat bot can look up. When the answer links none of its sources, their links are added at the end.

Each pass of the model that produces output counts one AI request, and the searches by meaning it runs count like vdb_search. Every plan includes a monthly allowance of AI requests: API Quota, Pricing. The allowance used is the one of the account that owns the index.

04 · Errors before the stream

ERROR_JSON_BODY_REQUIREDHTTP 200

The body is not JSON.

ERROR_MESSAGES_REQUIRED, ERROR_USER_MESSAGE_REQUIRED, ERROR_MAX_21_MESSAGESHTTP 200

No conversation, the last message is not the user's, or too many messages.

ERROR_MESSAGE_TOO_LONGHTTP 200

The last question is longer than 4000 characters.

ERROR_VISITOR_QUESTIONS_LIMITHTTP 200

This visitor asked 100 questions on this index in the last hour.

VECTOR_NOT_ALLOWED, ERROR_AI_MONTHLY_QUOTA_EXCEEDEDHTTP 200

AI is off on the plan of the index owner, or the allowance is used up.

ERROR_LLM_UNAVAILABLEHTTP 200

The model did not answer. Retry.

ERROR_NOT_CORE_OWNERHTTP 200

The index is not yours.

WRONG_API_HOSTHTTP 404

Called on opensolr.com.

ERROR_AUTHENTICATION_FAILEDHTTP 403

The email and API key do not match.

05 · Related

The same chat bot without code, on your site: Three ways to add the chat bot. The model alone, with your own tools: chat_completions.

Every error code and HTTP status of the API: API errors. Calls per minute and per hour: Rate limits.