Skip to content

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.

POST https://platform.ibou.com/api/v1/…
Endpoints and prices
EndpointsEach result contains
/v1/urls 1 unitThe source’s URL.
/v1/results 2 unitsThe source’s host, URL, title, an excerpt, and its language.
/v1/passage 3 unitsLike /v1/results, plus the best-matching passage.
/v1/page 5 unitsLike /v1/results, plus every passage of the page.

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

Request fields
FieldDescription
query string, required The search question, not blank. At most 200 characters.
max_results 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"
      }
    },
    …
  ]
}

Response fields
FieldDescription
queryThe question you sent.
max_resultsThe number of results asked for.
resultsThe results, best match first. With /v1/urls each result is just the source’s URL; otherwise it’s an object, described below.

Result fields

Result fields
FieldDescription
hostThe host name of the source’s site.
urlThe source’s address.
titleThe page title.
snippetA short excerpt of the page.
languageThe page language, e.g. fr.
passageThe page’s passage that best matches the question. Only with /v1/passage.
passages[]Every passage of the page. Only with /v1/page.
passage.chunk_id
passages[].chunk_id
The passage’s ID within the page.
passage.text
passages[].text
The passage’s text.
passages[].usedWhether 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:

Error status codes
StatusMeaning
400query or max_results is invalid, or the request body isn’t JSON.
401Missing or unknown API key.
403Your organization is suspended. Contact support.
404Unknown endpoint: the path matches none of the endpoints above.
408The request body didn’t arrive in time.
413Request body over 4 KiB.
415Missing Content-Type: application/json header.
422query is missing, a field is unknown, or a field has the wrong type.
429Your organization has no units left, or you’re sending requests too fast.
500Internal error. Try again; if it keeps happening, contact support.
502The search service failed. Try again in a moment.
503The search service is overloaded or briefly unavailable. Try again after the number of seconds in the Retry-After header.
504The search took too long. Try again in a moment.