DocumentationAPI

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
  1. Clés d’API et limites
  2. Requêtes vues par le serveur
  3. Journaux d’accès
  4. Erreurs
  5. API d’événements
  6. Champs d’un événement
  7. Réponses de l’API d’événements
  8. Relancer l’exploration
  9. API de recherche
  10. Collecte du traceur

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.

RouteCorpsPar appelDébit, par clé
POST /api/v1/hits1 Mo au plus, JSON500 requêtes600 appels par minute, partagés avec /api/v1/logs
POST /api/v1/logs1 Mo au plus, texte5 000 lignes600 appels par minute, partagés avec /api/v1/hits
POST /api/v1/events512 ko au plus, JSON100 événements3 000 appels par minute
POST /api/v1/crawlIgnoréUne relanceUne 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.

Requêtehttp
POST https://kreomnisindexation.com/api/v1/hits
Authorization: Bearer ki_live_…
Content-Type: application/json
ChampDescription
urlObligatoire. 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.
hostHô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.
tsInstant 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.
methodMéthode HTTP (GET, POST…).
statusCode de la réponse, de 100 à 599.
bytesTaille de la réponse, en octets.
msDurée de traitement côté serveur, en millisecondes (une heure au plus).
ipAdresse 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_agentUser-Agent du visiteur (300 caractères gardés). Une chaîne vide signifie : pas de User-Agent.
referrerRéférent, réduit à son origine et son chemin.
protocolHTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3.
content_typeType de la réponse, par exemple text/html.
languagePremière langue de l’en-tête Accept-Language, par exemple fr-FR.
purposeEn-tête Sec-Purpose ou Purpose (prefetch, prerender) : préchargement.
countryCode pays ISO en deux lettres, si votre serveur ou votre CDN le connaît déjà ; sinon il est déduit de l’adresse.
Corpsjson
{
  "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 :

202 Acceptedjson
{ "received": 3, "accepted": 2, "rejected": [{ "index": 2, "reason": "foreign_host" }] }
  • accepted compte les requêtes valides. Une requête refusée n’empêche pas les autres ; rejected en détaille 20 au plus, avec leur rang dans le lot et la raison : invalid (pas un objet, url absente 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.

Requêtehttp
POST https://kreomnisindexation.com/api/v1/logs?format=nginx
Authorization: Bearer ki_live_…
Content-Type: text/plain
FormatCe 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 :

202 Acceptedjson
{ "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é :

CodeErreurRouteCause
400bad_jsonhits, eventsLe corps n’est pas du JSON.
400invalidhitsPas de liste « hits », ou une liste vide.
400invalideventsÉvénement unique invalide, ou lot mal formé (champ « events » vide ou de plus de 100 éléments) ; « issues » détaille les problèmes.
400bad_formatlogsFormat inconnu : auto, caddy, nginx, apache.
401unauthorizedtoutesClé absente, invalide ou révoquée.
403plancrawlL’offre de l’espace ne comprend pas la collecte côté serveur ; le message dit laquelle la comprend.
409not_verifiedcrawlLa propriété du site n’est pas encore vérifiée.
413too_largehits, logs, eventsCorps trop gros (1 Mo pour hits et logs, 512 ko pour events), plus de 500 requêtes ou plus de 5 000 lignes.
429rate_limitedhits, logs, eventsDébit dépassé : réessayez après le délai de l’en-tête Retry-After (60 s).
429rate_limitedcrawlRelance déjà faite il y a moins de 10 minutes : l’en-tête Retry-After (et le champ retryAfter) donne les secondes à attendre.
502crawl_failedcrawlL’exploration n’a pas pu démarrer : réessayez dans quelques minutes.
503unavailabletoutesService momentanément indisponible : réessayez plus tard.

API d’événements#

Requêtehttp
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#

ChampTypeDescription
nametexte, obligatoire1 à 64 caractères : lettres, chiffres, espaces et _ . : ' ’ -. pageview pour une page vue, un nom e-commerce, ou votre propre événement.
urlURL, obligatoireAdresse 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.
iptexteAdresse IP du visiteur, pour rattacher l’événement à sa visite. Non conservée.
user_agenttexteUser-Agent du visiteur (500 caractères au plus). Sert aussi à reconnaître les robots.
referrertexteRéférent, réduit à son origine et son chemin.
propsobjetPropriétés : clés de 64 caractères, valeurs texte (300), nombre, booléen ou null.
revenueobjet{ "amount": nombre, "currency": "EUR" } ; devise ISO en trois lettres majuscules.
itemstableauProduits (100 au plus) : name obligatoire, id, category, variant, price, quantity.
order_idtexteNuméro de commande (100 caractères) : un achat n’est compté qu’une fois par numéro.
statusentierCode HTTP de la réponse (100 à 599), pour les passages de robots.
methodtexteMéthode HTTP (GET, HEAD…).
languagetexteLangue du visiteur, par exemple fr-FR.
countrytexteCode pays ISO en deux lettres majuscules, par exemple FR.
Corps d’un lotjson
{
  "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 ip ni user_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 :

202 Acceptedjson
{
  "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ésultatSignification
"duplicate": trueAchat 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).

Relance depuis la CIbash
# 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 :

202 Acceptedjson
{ "status": "started", "runId": 1234, "message": "Exploration relancée : …" }
RéponseSignification
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 planL’offre de l’espace ne comprend pas la collecte côté serveur.
409 not_verifiedLa propriété du site n’est pas encore vérifiée.
429 rate_limitedRelance 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) :

Requêtehttp
GET https://kreomnisindexation.com/api/search?q=pain+au+levain&limit=10&offset=0
ParamètreDescription
qLa requête, 200 caractères au plus.
limitNombre de résultats, 10 par défaut, 50 au plus.
offsetDécalage pour la pagination, 500 au plus.
200 OKjson
{
  "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_html contient des balises <mark> autour des termes trouvés.
  • click_url passe par Kreomnis pour compter le clic dans les performances du site, puis redirige vers la page. Utilisez url pour 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 429 au-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.