Docs
Endpoints
One search, four levels of detail: each endpoint returns the same sources ranked by relevance, more or less complete, at its own price.
https:// platform.ibou.com/ api/ v1/ …| Endpoints | Each result contains | Price per call |
|---|---|---|
/v1/urls 1 unit | The source’s URL. | 1 unit |
/v1/results 2 units | The source’s host, URL, title, an excerpt, and its language. | 2 units |
/v1/passage 3 units | Like /v1/results, plus the best-matching passage. | 3 units |
/v1/page 5 units | Like /v1/results, plus every passage of the page. | 5 units |
Authentication
Every request needs one of your organization’s API keys in the X-API-Key header. Create and manage keys on the API keys page.
To try it without writing code, the Playground runs a search with your organization’s units, no key to type.
Request
| Field | Type | Description |
|---|---|---|
query string, required | string, required | The search question, not blank. At most 200 characters. |
max_results integer, optional | integer, optional | Number of results to return, between 1 and 20. Defaults to 10. |
Example
cURL request example
curl -X POST https://platform.ibou.com/api/v1/passage \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{ "query": "pourquoi le ciel est bleu" }' Response
A JSON object, here for /v1/passage, cut to its first three results:
Response example
{
"query": "pourquoi le ciel est bleu",
"max_results": 10,
"results": [
{
"host": "meteofrance.com",
"url": "https://meteofrance.com/meteo-a-z/pourquoi-le-ciel-est-il-bleu",
"title": "Pourquoi le ciel est-il bleu ? | Météo-France",
"snippet": "Pourquoi le ciel est-il rouge le soir ? · Au moment du lever et du coucher du soleil, la lumière du soleil traverse une plus grande épaisseur d’atmosphère avant de parvenir jusqu’à notre œil. Sur ce long chemin dans l’atmosphère, les rayonnements de petites…",
"language": "fr",
"passage": {
"chunk_id": 1,
"text": "[Pourquoi le ciel est-il bleu ? | Météo-France]\n[## Pourquoi le ciel est-il rouge le soir ?]\nAu moment du lever et du coucher du soleil, la lumière du soleil traverse une plus grande épaisseur d’atmosphère avant de parvenir jusqu’à notre œil. Sur ce long chemin dans l’atmosphère, les rayonnements de petites longueurs d’onde, comme le bleu, sont complètement diffusés ; ce sont les couleurs orangées ou rouges, de plus grandes longueurs d’onde, qui vont parvenir à arriver jusqu’à nous pour embellir notre ciel de début ou fin de journée.\n"
}
},
{
"host": "www.meteo.be",
"url": "https://www.meteo.be/fr/infos/faq/phenomenes-meteorologiques/pourquoi-le-ciel-est-il-bleu",
"title": "IRM - Pourquoi le ciel est-il bleu?",
"snippet": "FAQ · Phénomènes météorologiques · Pourquoi le ciel est-il bleu? · La lumière solaire qui atteint la terre est diffusée par les molécules de l’air qu’elle rencontre. Le diamètre de ces molécules est beaucoup plus petit que celui des gouttelettes d’eau et…",
"language": "fr",
"passage": {
"chunk_id": 0,
"text": "[IRM - Pourquoi le ciel est-il bleu?]\n[# FAQ]\n[## Phénomènes météorologiques]\n[### Pourquoi le ciel est-il bleu?]\nLa lumière solaire qui atteint la terre est diffusée par les molécules de l’air qu’elle rencontre.\nLe diamètre de ces molécules est beaucoup plus petit que celui des gouttelettes d’eau et aussi plus petit que la longueur d’onde de la lumière visible (entre 0,4 et 0,7 micromètres).\nLes molécules composant l’air (essentiellement l’azote et l’oxygène) diffusent la lumière des courtes longueurs d’ondes (dans le violet et le bleu) nettement mieux que les longues (dans le rouge et l’orange). C’est ce qui explique qu’en observant un ciel dégagé de nuage, il nous apparaisse bleu.\nVous n'aimez pas notre image de fond? Pas de problème; il vous suffit de cocher la case ci-dessous pour désactiver cette image\n"
}
},
{
"host": "www.rtbf.be",
"url": "https://www.rtbf.be/article/pourquoi-le-ciel-est-il-bleu-11498508",
"title": "Pourquoi le ciel est-il bleu ? - RTBF Actus",
"snippet": "Une question de longueurs d’ondes · En fait, la couleur bleue du ciel n’est pas une fatalité : elle dépend principalement de la longueur d’onde des couleurs. Pour comprendre, il faut savoir que le soleil diffuse de la lumière dite blanche, qui est en réalité…",
"language": "fr",
"passage": {
"chunk_id": 0,
"text": "[Pourquoi le ciel est-il bleu ? - RTBF Actus]\n[## Une question de longueurs d’ondes]\nEn fait, la couleur bleue du ciel n’est pas une fatalité : elle dépend principalement de la longueur d’onde des couleurs. Pour comprendre, il faut savoir que le soleil diffuse de la lumière dite blanche, qui est en réalité un mélange de toutes les couleurs, chacune d’entre elle ayant une longueur d’ondes spécifique : on parle d’ondes plus ou moins courtes ou plus ou moins longues.\n"
}
},
…
]
} | Field | Description |
|---|---|
query | The question you sent. |
max_results | The number of results asked for. |
results | The results, best match first. With /v1/urls each result is just the source’s URL; otherwise it’s an object, described below. |
Result fields
| Field | Description |
|---|---|
host | The host name of the source’s site. |
url | The source’s address. |
title | The page title. |
snippet | A short excerpt of the page. |
language | The page language, e.g. fr. |
passage | The page’s passage that best matches the question. Only with /v1/passage. |
passages[] | Every passage of the page. Only with /v1/page. |
passage.chunk_idpassages[].chunk_id | The passage’s ID within the page. |
passage.textpassages[].text | The passage’s text. |
passages[].used | Whether this passage was used to rank the result. |
Units
Each call uses its endpoint’s price, in units, from your organization’s balance. A refused call (invalid key, not enough units) uses nothing. All of your organization’s API keys share the same balance. Check it on the Home page. Owners can buy more on the Units & billing page.
Errors
Errors come back with a JSON body and one of these status codes:
| Status | Meaning |
|---|---|
400 | query or max_results is invalid, or the request body isn’t JSON. |
401 | Missing or unknown API key. |
403 | Your organization is suspended. Contact support. |
404 | Unknown endpoint: the path matches none of the endpoints above. |
408 | The request body didn’t arrive in time. |
413 | Request body over 4 KiB. |
415 | Missing Content-Type: application/json header. |
422 | query is missing, a field is unknown, or a field has the wrong type. |
429 | Your organization has no units left, or you’re sending requests too fast. |
500 | Internal error. Try again; if it keeps happening, contact support. |
502 | The search service failed. Try again in a moment. |
503 | The search service is overloaded or briefly unavailable. Try again after the number of seconds in the Retry-After header. |
504 | The search took too long. Try again in a moment. |