Olindias Search docs
How to put Olindias Search on your website, and how to call its search and chat API from your own code.
On this page
What it does
Visitors find what they need on your website by searching it or asking it a question. Answers come only from your own pages and link to the pages they used; when your site does not cover a question, the assistant says so. Add the search box, the chat or both, one script tag each, or build your own interface on the same API the widgets use.
Set it up
- Sign up. Choose your plan on the Search pricing page: Start for free for Starter's 14-day free trial, Get Growth for Growth, or Talk to us for Business. Then enter your name and email and add a card at checkout; for the trial, nothing is charged if you cancel before it ends. Afterwards you sign in at search.olindias.com with your Google account or a code we email you.
- Add your website. Choose Connect your website (for another website later, Add domain in the domain menu), enter your address starting with
https://and choose Start learning. We start reading your site straight away, from its home page, every page we can reach up to your plan's page limit. Advanced settings let you cap the number of pages, start from a particular page or include subdomains. Follow the read in Knowledge Base: your site is ready to search when its job shows Completed, usually within minutes. - Paste a script tag. Open Widget Setup, choose Chat or Search, try it on your own content, then copy the tag under Install and paste it into your site before the closing
</body>tag. One tag per widget: to have both, paste both. Searches start arriving in your dashboard right away.
Example, the chat widget's tag:
<script
src="https://search.olindias.com/static/chat-widget.js"
data-token="YOUR_TOKEN"
data-api-url="https://search.olindias.com/api">
</script>
The search widget's tag is the same with search-widget.js in place of chat-widget.js.
Your public token is in Settings, in the Domain card, under Domain Token, with a button to copy it. Each website you add has its own. It is public by design: it sits in your page source, and rate limits protect it. Rotate gives you a new token and stops the old one at once, so update your script tags and code straight after. The widgets and the API answer while your plan or trial is active.
The API
Search and chat over one website's content, the same API the widgets use. The full description is the OpenAPI document.
Address and authentication
Every endpoint is under https://search.olindias.com/api/v1. Send your website's public token with each request:
Authorization: Bearer YOUR_TOKEN
A missing, unknown or inactive token gets 401 with the code invalid_token.
Search: GET /search
The pages that best match a query, best first. Searches are not metered.
| Parameter | What it is |
|---|---|
q |
Required. What to search for, at most 500 characters. |
limit |
Optional. How many results at most, 1 to 100. Leave it out for every matching page. |
Example request:
curl "https://search.olindias.com/api/v1/search?q=pricing&limit=3" \
-H "Authorization: Bearer YOUR_TOKEN"
Example response:
{
"results": [
{
"url": "https://example.com/pricing",
"title": "Plans and pricing",
"snippet": "Every plan includes unlimited searches…"
}
],
"search_id": 4821
}
Each result has url, title (from the best-matching passage) and snippet (the start of that passage, up to 200 characters plus an ellipsis). results is empty when nothing matches. Keep search_id for recording clicks; it is null when the search could not be recorded.
Record a click: POST /search/clicks
Records which result a visitor opened, which shows you what people find. Send it when a visitor opens a result, with keepalive: true so it survives the page change.
| Field | What it is |
|---|---|
search_id |
Required. The search_id of the search the result came from. |
clicked_url |
Required. The result's URL, at most 2,048 characters. |
rank |
Optional. The result's position in the list, starting at 1. |
Example request:
fetch("https://search.olindias.com/api/v1/search/clicks", {
method: "POST",
keepalive: true,
headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
body: JSON.stringify({ search_id: 4821, clicked_url: "https://example.com/pricing", rank: 1 }),
})
The answer is 204 with no body. A search_id that is not your site's gets the same 204 and records nothing.
Ask: POST /chat
Answers a visitor's question from your site's content, streamed as server-sent events. The assistant decides whether and what to search, may search several times, then writes an answer in Markdown that links its sources inline as [label](url). A question your site has nothing on, or one that is not about your site, is declined politely.
| Field | What it is |
|---|---|
query |
Required. The visitor's question, at most 1,000 characters. |
history |
Optional. The conversation so far, oldest first, without the current question: a list of { "role": "user" or "assistant", "content": "…" }. Only the last 10 messages are used; more than 50 is refused. A message over 4,000 characters is cut to that length, and one over 20,000 is refused with 422. |
conversation_id |
Optional. Leave it out on the first turn and send back the one the start event gives you on every later turn. |
The server keeps no history. Send the earlier turns in history with each request, the assistant's answers as the Markdown they arrived as.
Example request body:
{
"query": "Can I return an item I bought on sale?",
"history": [
{ "role": "user", "content": "What is your returns policy?" },
{ "role": "assistant", "content": "You can return unused items within 30 days…" }
],
"conversation_id": "5f0c7a52-3b1e-4b8e-9a35-2d6f0c8e41b7"
}
The answer has the type text/event-stream. Each event is an event: <type> line and a data: <json> line, then a blank line; the JSON carries type too. In order:
| Event | When | Fields |
|---|---|---|
start |
Always first. | conversation_id |
searching |
Each time the assistant searches, zero or more times. | query, the search it wrote |
reading |
After each search. | count, how many passages it found |
token |
The answer, in pieces. | content: join every piece in order, then render the Markdown |
sources |
Once, after the answer. | sources: up to 10 pages, best first, each with url, title, section and label |
done |
Last, when the turn succeeds. | message_id, answered and reason |
error |
Last, when the turn fails, in place of sources and done. |
code and message |
done.answered tells you whether the assistant answered. When it is false, reason says why: not_found (nothing on your site answers it) or off_topic (not about your site). The polite refusal still arrives as token events; that is the moment to offer another way to get help. An empty sources list does not by itself mean the assistant declined. message_id is for rating the answer; it is null when nothing was stored.
An error event's code is model_error, model_unavailable, search_unavailable, quota_exceeded (the assistant is unavailable for your site for now, for instance at its monthly limit) or internal_error, and its message can be shown to the visitor. Text that arrived before it is incomplete.
Example, reading the stream with fetch in JavaScript:
const res = await fetch("https://search.olindias.com/api/v1/chat", {
method: "POST",
headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
body: JSON.stringify({ query, history, conversation_id: conversationId }),
})
if (!res.ok) throw new Error((await res.json()).error.code)
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ""
let answer = ""
for (;;) {
const { value, done } = await reader.read()
if (done) break
buffer += value
let end
while ((end = buffer.indexOf("\n\n")) !== -1) {
const block = buffer.slice(0, end)
buffer = buffer.slice(end + 2)
const line = block.split("\n").find((l) => l.startsWith("data:"))
if (!line) continue
const event = JSON.parse(line.slice(5))
if (event.type === "start") conversationId = event.conversation_id
else if (event.type === "token") render((answer += event.content))
else if (event.type === "sources") showSources(event.sources)
else if (event.type === "done" && !event.answered) offerContactForm(event.reason)
else if (event.type === "error") showError(event.message)
// any other type: ignore it
}
}
render, showSources, offerContactForm and showError stand for your own interface. Render the Markdown safely: allow only http and https links.
Rate an answer: POST /chat/feedback
Records whether an answer helped, by the message_id of its done event. One rating per answer: a second replaces the first.
| Field | What it is |
|---|---|
message_id |
Required. From the answer's done event. |
rating |
Required. 1 for helpful, -1 for not helpful. |
reason |
Optional, for a -1: what was wrong, such as incorrect, incomplete, unanswered or your own words, at most 1,000 characters. |
Example request body:
{ "message_id": 1234, "rating": -1, "reason": "incomplete" }
The answer is 204 with no body, also for a message_id that is not your site's, which records nothing.
Errors
Errors are JSON, including those of /chat that happen before the stream starts. Example, a request with a wrong token:
{ "error": { "code": "invalid_token", "message": "The token is missing, unknown or not active." } }
Branch on code, never on message, which is for people and may change. The codes are invalid_token (401), invalid_request (422), rate_limited (429), not_found (404), method_not_allowed (405), search_unavailable (503) and internal_error (500). invalid_request adds detail, one entry per field that failed, each with loc, msg and type. Once a chat stream has started, the status is 200 and a failure arrives as an error event instead.
Rate limits
Limits count per visitor address and per token:
| Endpoint | Per address | Per token |
|---|---|---|
POST /chat |
10 a minute and 60 an hour | 120 a minute |
GET /search |
60 a minute | 600 a minute |
POST /chat/feedback |
30 a minute | 600 a minute |
POST /search/clicks |
60 a minute | 1,200 a minute |
Over a limit the answer is 429 with the code rate_limited and a Retry-After header: wait that many seconds before trying again.
Calling it from a browser
Every endpoint accepts requests from any origin, without cookies, so a page can call the API directly with its public token. Scripts can read Retry-After.
Versioning
The version is the first part of the path, /v1. Within v1 changes only add things: new endpoints, new optional parameters, new response fields, new chat event types and new error codes. Your code must ignore fields and event types it does not know. A breaking change gets a new version, /v2, and a path being retired sends Deprecation and Sunset headers before it goes.
Help
Questions about setting up Search or using the API: sales@olindias.com. The complete reference, every field included, is the OpenAPI document.