API
Les API à clé reçoivent ce que voit votre serveur : chaque requête, les lignes de vos journaux d’accès, et les événements qu’il est seul à connaître ; elles relancent aussi l’exploration après un déploiement. L’API de recherche Kreomnis, elle, est ouverte.
Sur cette page
Clés d’API et limites#
Chaque appel porte une clé propre au site, créée dans la console (voir Collecte côté serveur), dans l’en-tête Authorization: Bearer ki_live_…. Elle ne s’utilise que côté serveur ; une clé révoquée cesse de fonctionner en 10 secondes au plus. Les clés d’API dépendent de l’offre de l’espace du site.
| Route | Corps | Par appel | Débit, par clé |
|---|---|---|---|
POST /api/v1/hits | 1 Mo au plus, JSON | 500 requêtes | 600 appels par minute, partagés avec /api/v1/logs |
POST /api/v1/logs | 1 Mo au plus, texte | 5 000 lignes | 600 appels par minute, partagés avec /api/v1/hits |
POST /api/v1/events | 512 ko au plus, JSON | 100 événements | 3 000 appels par minute |
POST /api/v1/crawl | Ignoré | Une relance | Une par site toutes les 10 minutes |
Côté site, n’attendez jamais la réponse pour servir une page, et ne réessayez pas en boucle : envoyez après la réponse, par lots, avec un délai court et un recul après un échec, comme les extraits fournis.
Requêtes vues par le serveur#
Chaque requête reçue par votre site, telle que la voit votre serveur, pour le journal du trafic. Le corps est un lot { "hits": [ … ] } de 1 à 500 requêtes ; seul url est obligatoire.
POST https://kreomnisindexation.com/api/v1/hits Authorization: Bearer ki_live_… Content-Type: application/json
| Champ | Description |
|---|---|
url | Obligatoire. URL absolue (http ou https) ou chemin (/produits?tri=prix), 8 192 caractères au plus. La requête (?…) sert à repérer les attaques : seuls les noms des paramètres sont gardés. |
host | Hôte demandé, quand url est un chemin (le port est ignoré). Sans lui, le domaine du site. Il doit être le domaine du site ou l’un de ses sous-domaines. |
ts | Instant de la requête : date ISO 8601 (millisecondes et Z acceptés) ou secondes Unix. Absent, illisible, dans le futur ou de plus de 7 jours : l’instant de réception. |
method | Méthode HTTP (GET, POST…). |
status | Code de la réponse, de 100 à 599. |
bytes | Taille de la réponse, en octets. |
ms | Durée de traitement côté serveur, en millisecondes (une heure au plus). |
ip | Adresse IPv4 ou IPv6 du visiteur. Jamais enregistrée : elle donne le pays, le réseau, l’empreinte du jour du visiteur et, pour le trafic non humain, le préfixe du réseau. Sans elle, ni pays, ni réseau, ni visite. |
user_agent | User-Agent du visiteur (300 caractères gardés). Une chaîne vide signifie : pas de User-Agent. |
referrer | Référent, réduit à son origine et son chemin. |
protocol | HTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3. |
content_type | Type de la réponse, par exemple text/html. |
language | Première langue de l’en-tête Accept-Language, par exemple fr-FR. |
purpose | En-tête Sec-Purpose ou Purpose (prefetch, prerender) : préchargement. |
country | Code pays ISO en deux lettres, si votre serveur ou votre CDN le connaît déjà ; sinon il est déduit de l’adresse. |
{
"hits": [
{ "ts": "2026-11-19T10:15:00.120Z", "method": "GET", "url": "/produits/pain?tri=prix", "host": "exemple.fr",
"status": 200, "bytes": 18432, "ms": 42.5, "ip": "IP_DU_VISITEUR", "user_agent": "USER_AGENT_DU_VISITEUR",
"referrer": "https://www.google.fr/", "protocol": "HTTP/2", "content_type": "text/html", "language": "fr-FR" }
]
}Un appel valide répond 202 :
{ "received": 3, "accepted": 2, "rejected": [{ "index": 2, "reason": "foreign_host" }] }acceptedcompte les requêtes valides. Une requête refusée n’empêche pas les autres ;rejecteden détaille 20 au plus, avec leur rang dans le lot et la raison :invalid(pas un objet,urlabsente ou trop longue),bad_url(ni http(s) ni chemin, hôte illisible),foreign_host(hôte hors du domaine du site).- Un fichier statique servi sans erreur est accepté mais n’est enregistré qu’avec le réglage « Garder aussi les fichiers statiques servis sans erreur » (voir Trafic).
- Les pages, flux et fichiers lus par des robots alimentent aussi les rapports Robots et Comportement. L’audience, elle, ne reçoit jamais ces requêtes.
Journaux d’accès#
Les lignes brutes d’un journal d’accès, une par ligne, de 5 000 lignes et 1 Mo au plus par appel ; une ligne de plus de 8 Ko est ignorée. Le paramètre format vaut auto, caddy, nginx ou apache (par défaut : auto). L’expéditeur kreomnis-logs.mjs fait tout cela pour vous.
POST https://kreomnisindexation.com/api/v1/logs?format=nginx Authorization: Bearer ki_live_… Content-Type: text/plain
| Format | Ce qui est lu |
|---|---|
| Caddy (JSON) | Adresse (request.client_ip, sinon remote_ip), méthode, uri, hôte, protocole, en-têtes User-Agent, Referer, Accept-Language et Sec-Purpose, status, size, duration (en secondes), ts, type de la réponse. |
| nginx, Apache (« combined ») | Adresse, date, ligne de requête (méthode, cible, protocole), code, taille, référent et User-Agent ; l’hôte en tête de ligne et la durée en fin de ligne sont lus s’ils sont là. Une durée avec décimales est en secondes ($request_time de nginx), une durée entière en microsecondes (%D d’Apache). |
Un appel valide répond 202 :
{ "lines": 1000, "accepted": 990, "skipped": 10 }skipped compte les lignes écartées : illisibles, d’un autre hôte que le site, ou invalides. Un envoi de plus de 5 000 lignes est refusé en entier. Les lignes ne sont jamais gardées : seuls les champs du journal du trafic en sont tirés, sans l’adresse IP.
Erreurs#
Une erreur répond par un code HTTP et un corps { "error": "…", "message": "…" }, sans rien qui identifie le site ni la clé :
| Code | Erreur | Route | Cause |
|---|---|---|---|
| 400 | bad_json | hits, events | Le corps n’est pas du JSON. |
| 400 | invalid | hits | Pas de liste « hits », ou une liste vide. |
| 400 | invalid | events | Événement unique invalide, ou lot mal formé (champ « events » vide ou de plus de 100 éléments) ; « issues » détaille les problèmes. |
| 400 | bad_format | logs | Format inconnu : auto, caddy, nginx, apache. |
| 401 | unauthorized | toutes | Clé absente, invalide ou révoquée. |
| 403 | plan | crawl | L’offre de l’espace ne comprend pas la collecte côté serveur ; le message dit laquelle la comprend. |
| 409 | not_verified | crawl | La propriété du site n’est pas encore vérifiée. |
| 413 | too_large | hits, logs, events | Corps trop gros (1 Mo pour hits et logs, 512 ko pour events), plus de 500 requêtes ou plus de 5 000 lignes. |
| 429 | rate_limited | hits, logs, events | Débit dépassé : réessayez après le délai de l’en-tête Retry-After (60 s). |
| 429 | rate_limited | crawl | Relance déjà faite il y a moins de 10 minutes : l’en-tête Retry-After (et le champ retryAfter) donne les secondes à attendre. |
| 502 | crawl_failed | crawl | L’exploration n’a pas pu démarrer : réessayez dans quelques minutes. |
| 503 | unavailable | toutes | Service momentanément indisponible : réessayez plus tard. |
API d’événements#
POST https://kreomnisindexation.com/api/v1/events Authorization: Bearer ki_live_… Content-Type: application/json
Pour les événements que seul votre serveur connaît : paiement confirmé par webhook, abonnement, commande saisie en administration. Le corps est un événement, ou un lot { "events": [ … ] } de 1 à 100 événements.
Champs d’un événement#
| Champ | Type | Description |
|---|---|---|
name | texte, obligatoire | 1 à 64 caractères : lettres, chiffres, espaces et _ . : ' ’ -. pageview pour une page vue, un nom e-commerce, ou votre propre événement. |
url | URL, obligatoire | Adresse de la page, sur le domaine du site ou un sous-domaine. Envoyez l’origine et le chemin ; seuls les paramètres utm_* sont exploités. |
ip | texte | Adresse IP du visiteur, pour rattacher l’événement à sa visite. Non conservée. |
user_agent | texte | User-Agent du visiteur (500 caractères au plus). Sert aussi à reconnaître les robots. |
referrer | texte | Référent, réduit à son origine et son chemin. |
props | objet | Propriétés : clés de 64 caractères, valeurs texte (300), nombre, booléen ou null. |
revenue | objet | { "amount": nombre, "currency": "EUR" } ; devise ISO en trois lettres majuscules. |
items | tableau | Produits (100 au plus) : name obligatoire, id, category, variant, price, quantity. |
order_id | texte | Numéro de commande (100 caractères) : un achat n’est compté qu’une fois par numéro. |
status | entier | Code HTTP de la réponse (100 à 599), pour les passages de robots. |
method | texte | Méthode HTTP (GET, HEAD…). |
language | texte | Langue du visiteur, par exemple fr-FR. |
country | texte | Code pays ISO en deux lettres majuscules, par exemple FR. |
{
"events": [
{ "name": "pageview", "url": "https://exemple.fr/produits/pain", "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)", "status": 200, "method": "GET" },
{ "name": "purchase", "url": "https://exemple.fr/merci", "ip": "IP_DU_VISITEUR", "user_agent": "USER_AGENT_DU_VISITEUR",
"order_id": "A-1001", "revenue": { "amount": 42.5, "currency": "EUR" },
"items": [{ "id": "SKU-42", "name": "Pain au levain", "price": 4.5, "quantity": 2 }] }
]
}- Une page vue (
pageview) dont le User-Agent est celui d’un robot va dans le rapport Robots ; avec un User-Agent de navigateur, elle compte dans l’audience. Dans les deux cas, elle entre aussi dans le journal du trafic. - Pour envoyer tout le trafic, préférez
/api/v1/hits: une page vue envoyée ici avec un User-Agent de navigateur ferait doublon avec celle du traceur. - Les autres événements envoyés avec la clé ne sont jamais classés robots, même sans User-Agent de navigateur (webhook de paiement, tâche planifiée).
- Sans
ipniuser_agent, ceux de la requête (votre serveur) servent à l’empreinte du visiteur, jamais au pays ni au réseau.
Réponses de l’API d’événements#
Un appel valide répond 202, avec le détail de chaque événement :
{
"received": 2,
"accepted": 2,
"results": [
{ "accepted": true, "bot": "GPTBot (OpenAI)" },
{ "accepted": true }
]
}accepted compte les événements enregistrés, doublons exclus. Dans un lot, un événement invalide est écarté sans bloquer les autres : son résultat porte "reason": "invalid" et les problèmes relevés.
| Résultat | Signification |
|---|---|
"duplicate": true | Achat déjà reçu avec ce numéro de commande. |
"reason": "invalid" | Champs invalides (détail dans issues). |
"reason": "foreign_host" | L’URL n’est pas sur le domaine du site. |
"reason": "bad_url" | URL illisible ou d’un autre protocole que http(s). |
"bot": "<nom>" | Événement venant d’un robot : gardé à part (rapports Robots et Comportement), hors audience. |
Erreurs : voir Erreurs.
Relancer l’exploration#
Après un déploiement, votre intégration continue peut demander à KreomnisBot de relire le site, comme le bouton « Explorer » de la console : robots.txt, les sitemaps, l’accueil et les pages dues sont relus, puis le planificateur mène le passage à son terme. Même clé que les autres API, corps ignoré, une relance par site toutes les 10 minutes au plus. Elle va avec la collecte côté serveur, selon l’offre de l’espace (voir Offres et abonnement).
# Après un déploiement : relancer l'exploration du site (une fois toutes les 10 minutes au plus) curl -X POST https://kreomnisindexation.com/api/v1/crawl \ -H "Authorization: Bearer $KREOMNIS_API_KEY" \ --max-time 60
La réponse attend la fin de la découverte : prévoyez une minute d’attente au plus. Un appel accepté répond 202 :
{ "status": "started", "runId": 1234, "message": "Exploration relancée : …" }| Réponse | Signification |
|---|---|
202 "started" | Un passage d’exploration est ouvert ; runId est son identifiant. |
202 "running" | Une exploration était déjà en cours (planificateur ou console) : elle se poursuit, runId est le passage en cours. |
403 plan | L’offre de l’espace ne comprend pas la collecte côté serveur. |
409 not_verified | La propriété du site n’est pas encore vérifiée. |
429 rate_limited | Relance déjà faite il y a moins de 10 minutes : Retry-After donne les secondes à attendre. |
Gardez la clé dans les secrets de votre intégration continue, jamais dans le dépôt.
API de recherche#
La recherche Kreomnis est interrogeable en JSON, sans clé, depuis un serveur ou un navigateur (CORS ouvert) :
GET https://kreomnisindexation.com/api/search?q=pain+au+levain&limit=10&offset=0
| Paramètre | Description |
|---|---|
q | La requête, 200 caractères au plus. |
limit | Nombre de résultats, 10 par défaut, 50 au plus. |
offset | Décalage pour la pagination, 500 au plus. |
{
"query": "pain au levain",
"total": 12,
"results": [
{
"title": "Pain au levain",
"url": "https://exemple.fr/produits/pain",
"domain": "exemple.fr",
"snippet_html": "… notre <mark>pain</mark> <mark>au</mark> <mark>levain</mark> …",
"position": 1,
"click_url": "https://kreomnisindexation.com/r/…"
}
]
}snippet_htmlcontient des balises<mark>autour des termes trouvés.click_urlpasse par Kreomnis pour compter le clic dans les performances du site, puis redirige vers la page. Utilisezurlpour un lien direct.- Seules les pages indexées des sites vérifiés qui acceptent d’apparaître dans la recherche sont renvoyées.
- Débit : 120 requêtes par minute et par adresse IP (réponse
429au-delà).
Collecte du traceur#
L’adresse https://kreomnisindexation.com/api/collect reçoit les mesures du traceur k.js et du pixel Shopify. Son format est interne et peut évoluer : pour envoyer des événements depuis votre code, utilisez la fonction kreomnis() du traceur (Événements et objectifs) ou les API ci-dessus.
Une question sans réponse ici ? Consultez les questions fréquentes.