API

Deux API publiques : l’API d’événements, authentifiée par une clé de site, pour la collecte côté serveur ; l’API de recherche Kreomnis, ouverte, en JSON.

Sur cette page

API d’événements
Champs d’un événement
Réponses
API de recherche
Collecte du traceur

API d’événements#

Requêtehttp

POST https://kreomnisindexation.com/api/v1/events
Authorization: Bearer ki_live_…
Content-Type: application/json

La clé se crée dans la console (voir Collecte côté serveur) et ne s’utilise que côté serveur. Le corps est un événement, ou un lot { "events": [ … ] } de 1 à 100 événements.

Limite	Valeur
Taille du corps	512 ko au plus
Événements par lot	100 au plus
Débit	3 000 requêtes par minute et par clé
Révocation	Effective en 10 secondes au plus

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.

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.
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) sont utilisés.

Réponses#

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é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).
`"reason": "bot"`	Événement autre qu’une page vue venant d’un robot (via le traceur).

Code	Erreur	Cause
400	`bad_json`	Corps qui n’est pas du JSON.
400	`invalid`	Événement unique invalide, ou lot mal formé (champ events vide ou de plus de 100 éléments).
401	`unauthorized`	Clé absente, invalide ou révoquée.
413	`too_large`	Corps de plus de 512 ko.
429	`rate_limited`	Plus de 3 000 requêtes par minute ; réessayez après le délai de l’en-tête Retry-After (60 s).
503	`unavailable`	Service momentanément indisponible.

Côté site, n’attendez jamais la réponse pour servir une page, et ne réessayez pas en boucle : un délai court et les erreurs ignorées, comme dans les extraits fournis.

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è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.

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 l’API d’événements ci-dessus.

Une question sans réponse ici ? Consultez les questions fréquentes.