Aller au contenu
kosto kosto API v1
OpenAPI Retour au tableau de bord

Kosto API · v1

API Kosto, documentation :
l’autorité des domaines, dans vos propres outils.

Interrogez en HTTP le score d’autorité que vous voyez dans le tableau de bord, les domaines référents, la comparaison côte à côte et l’audit spam. Chaque réponse est en JSON, les noms de champs sont écrits en snake_case et chaque point de terminaison ci-dessous est accompagné d’un exemple fonctionnel.

Adresse de base
Point de terminaison
7
Limite par minute
120
Format
JSON
Authentification
Clé API

Score d’autorité

Un score de 0 à 100, les classements et les composantes qui forment le score. Un seul domaine, ou dix côte à côte.

Domaines référents

Domaines qui font un lien vers un domaine, classés par score ; vous fixez le score minimal.

Audit spam

Score de spam et motifs pour les traces d’abus comme les jeux d’argent, le contenu pour adultes, les produits pharmaceutiques et les contrefaçons.

  • Tous les points de terminaison se trouvent sous /api/v1. La version fait partie de l’adresse.
  • Les requêtes et les réponses sont au format JSON en UTF-8. Les dates sont écrites au format ISO 8601 (UTC).
  • Définition lisible par machine : téléchargez le document OpenAPI 3.1.

Premiers pas

Démarrage rapide

Trois étapes entre l’obtention d’une clé et la première réponse.

  1. 1

    Obtenir une clé

    Créez une clé ci-dessous. La clé n’est visible qu’au moment de sa création ; copiez-la et conservez-la en lieu sûr.

  2. 2

    Envoyer la première requête

    Envoyez la clé dans l’en-tête Authorization. L’exemple de droite est prêt dans le langage de votre choix ; remplacez YOUR_API_KEY par votre propre clé.

  3. 3

    Lire la réponse

    Le champ authority_score est le score de 0 à 100. Si found vaut false, le domaine ne figure pas dans l’index de liens ; ce n’est pas une erreur et la réponse est 200. score_source indique le type de score : data est fondé sur des données, tandis que standard et calibrated sont des scores approximatifs.

Sous chaque point de terminaison, le volet Essayer vous permet d’envoyer la requête directement depuis votre navigateur. La clé est conservée uniquement dans la mémoire de cet onglet, n’est enregistrée nulle part, et aucune requête n’est envoyée tant que vous n’appuyez pas sur le bouton.

Premiers pas

Authentification

Tous les points de terminaison, sauf /api/v1/openapi.json, exigent une clé API. Une clé commence par op_ et compte 35 caractères au total. Utilisez l’un des deux en-têtes ci-dessous ; les deux font le même travail.

En-tête HTTPFormat
AuthorizationBearer op_… (Bearer n’est pas sensible à la casse)
X-API-Keyop_…

Protéger la clé

  • Le serveur ne conserve pas la clé elle-même, mais son empreinte SHA-256. Si vous la perdez, générez-en une nouvelle et révoquez l’ancienne.
  • Conservez la clé dans une variable d’environnement ou dans votre coffre à secrets. Ne la placez ni dans le code source, ni dans des dépôts publics, ni dans du code exécuté par le navigateur.
  • Une clé révoquée reçoit 403 key_revoked. Si la clé est absente ou mal formée, la réponse est 401.
  • Aucun en-tête CORS n’est envoyé ; le code navigateur d’un autre site ne peut donc pas lire cette API (cross_site_forbidden). Les scripts, la ligne de commande et le code côté serveur fonctionnent sans aucun problème.
  • En mode compte, une clé appartient à un compte et est décomptée selon le forfait de ce compte ; une clé dont le compte est suspendu, ou qui n’est liée à aucun compte, reçoit 403.

Premiers pas

Limites de débit et quotas

Il existe deux limites distinctes : la limite de débit par minute est la même pour toutes les clés, tandis que les quotas mensuels et quotidiens dépendent de votre forfait.

Limite de débit : 120 requêtes par minute

Chaque clé peut effectuer 120 requêtes dans une fenêtre fixe de 60 secondes. La fenêtre s’ouvre avec la première requête de la clé, se ferme 60 secondes plus tard, puis le compteur est remis à zéro. Les requêtes qui n’envoient pas de clé valide sont comptées dans une fenêtre commune par adresse client. Les requêtes rejetées (comme 401 ou 400) sont également comptées dans la fenêtre. Chaque réponse /api/v1 comporte ces en-têtes :

En-tête HTTPSignification
X-RateLimit-LimitNombre de requêtes autorisées par fenêtre (120).
X-RateLimit-RemainingNombre de requêtes restantes dans la fenêtre en cours.
X-RateLimit-ResetMoment de fermeture de la fenêtre, en secondes Unix.
Retry-AfterLe nombre de secondes à attendre pour les réponses 429 et 503.

Lorsque la limite est dépassée, la réponse est 429 rate_limited. Attendez le délai indiqué dans Retry-After puis réessayez ; réessayer sans attendre ne fait que remplir davantage la fenêtre.

Quotas du forfait

En mode compte, chaque appel décompte une unité du compteur de requêtes API. Une analyse en masse consomme autant de lignes d’analyse en masse qu’elle contient de lignes, et un audit spam consomme un audit spam. Un appel échoué restitue ce qu’il a consommé. Un audit spam du même domaine le même jour n’est pas recompté (sauf avec fresh=1).

ForfaitClé APIRequêtes API / moisLignes d’analyse en masse / jourAudits spam / jour

Les quotas quotidiens et mensuels sont réinitialisés à minuit et au début du mois, à l’heure de la Turquie (UTC+3). Lorsqu’un quota est épuisé, la réponse est 429 quota_exceeded ; le message indique quel compteur est épuisé, votre consommation et votre forfait. Pour les tarifs, consultez la page des forfaits.

Premiers pas

Codes d’erreur

Les erreurs arrivent avec un code d’état HTTP et toujours le même corps. Le code est stable ; votre programme doit donc s’appuyer dessus. Le message est une description écrite pour les humains et peut changer ; il est en anglais par défaut, et vous pouvez choisir une autre langue avec l’en-tête Accept-Language ou X-Kosto-Lang.

StatutCodeQuand
  • Pour les réponses 5xx et 429, attendez le délai indiqué par l’en-tête Retry-After s’il est présent ; ne répétez pas une requête ayant reçu une réponse 4xx telle quelle, corrigez-la.
  • Pour une réponse 405, l’en-tête Allow indique la méthode prise en charge par le point de terminaison. HEAD est traité comme GET.
  • Pendant le chargement de l’index de liens, les requêtes de références peuvent renvoyer 503 graph_unavailable ; réessayez après le délai Retry-After: 15.

Premiers pas

Pagination et analyses en masse

L’API n’utilise ni curseurs (cursor) ni numéros de page. Les points de terminaison qui renvoient des listes répondent en une seule fois, et la taille de la réponse est limitée par des paramètres.

Point de terminaisonRègle
GET /backlinkslimit vaut 1 000 au maximum (100 par défaut). Le serveur sélectionne d’abord les meilleures références selon le score ; le filtre min_score s’applique parmi les 1 000 meilleures références selon la position de liens. C’est pourquoi, avec un filtre, returned peut être inférieur à limit. total est le nombre total de références, indépendamment du filtre.
GET /compareEntre 2 et 10 domaines. Les écritures menant au même site se regroupent sur une seule ligne ; après réduction, il doit rester au moins deux sites différents.
POST /bulkAu maximum 1 000 domaines par requête, et le corps fait 1 Mo au maximum. Si vous dépassez ces limites, vous recevez too_many_domains (400) ou payload_too_large (413). Les lignes vides sont ignorées, un même site est fusionné en une seule ligne, et les entrées invalides restent à leur place avec valid: false ; l’ordre est celui de la première apparition.

Découper les grandes listes

Si vous avez plus de 1 000 domaines, découpez la liste en blocs de 1 000 et envoyez-les les uns après les autres. Chaque bloc est une requête et compte dans la limite par minute ; en mode compte, il consomme en plus autant de quota d’analyses en masse que de lignes.

Autres

Versions et journal des modifications

La version fait partie de l’adresse : /api/v1. Le champ info.version du document OpenAPI indique la version du document pour cette version de l’API.

  • De nouveaux points de terminaison et de nouveaux champs dans les réponses peuvent être ajoutés sans changer de version. Nous attendons de votre client qu’il ignore les champs qu’il ne connaît pas.
  • Les changements incompatibles, comme modifier le type ou le sens d’un champ existant ou supprimer un champ, arrivent avec une nouvelle version (/api/v2).
  • Les textes de message peuvent changer. Appuyez-vous sur les valeurs de code et sur les codes d’état HTTP.
  1. 1.0.0Version actuelle

    Première version. Sept points de terminaison : domain, backlinks, compare, bulk, spam, usage et openapi.json.

    • Authentification par clé : Authorization: Bearer ou X-API-Key.
    • Limite de débit de 120 requêtes par minute et en-têtes X-RateLimit-*.
    • Format d’erreur : { "error": { "code", "message" } }.

Autres

Questions fréquentes

Domaine introuvable : est-ce une erreur ?

Non. Pour un domaine absent de l’index de liens, la réponse est 200 avec found: false. Dans ce cas, subdomains et referring_domains valent null. Une entrée invalide (un texte qui n’est pas un domaine) renvoie en revanche 400 invalid_domain.

Puis-je envoyer une URL ?

Oui. Le paramètre domain accepte un domaine ou une URL. https://www.example.com/page devient example.com dans la réponse. Il en va de même pour bulk et compare.

Pourquoi le nombre de domaines référents vaut-il parfois null ?

referring_domains vaut null si le domaine est absent du graphe de liens ou si le graphe ne peut pas répondre à cet instant. backlinks renvoie 503 graph_unavailable tant que le graphe n’est pas prêt.

Le score est-il approximatif ou basé sur les données ?

Consultez le champ score_source. S’il vaut data, le score a été calculé à partir de données de liens et de trafic mesurées ; le tableau de bord l’affiche avec un badge fondé sur des données et un point plein. standard et calibrated sont des scores approximatifs ; le tableau de bord leur attribue un badge approximatif et un point vide. Lorsque score_low et score_high sont présents, ils donnent la plage attendue du score, et le tableau de bord la dessine sous forme d’arc sur le cadran. Si les deux valent null, aucune plage n’est communiquée ; cela ne signifie pas une plage de largeur nulle.

Pourquoi le nombre de références affiché dans le tableau de bord peut-il différer de celui de l’API ?

referring_domains correspond toujours au nombre de domaines référents comptés dans l’index de liens, et le point de terminaison backlinks liste ces domaines par leur nom. Le tableau de bord affiche un seul nombre dans l’en-tête : celui des données de recherche si elles ont été ouvertes pour le domaine, sinon celui de l’index de liens. Lorsque le nombre issu des données de recherche figure dans l’en-tête, le nombre de l’index de liens apparaît dans le détail sous la carte, comme le nombre « que nous pouvons lister par nom ». Les deux nombres sont mesurés selon des méthodes différentes ; l’un ne contredit pas l’autre.

Pourquoi l’audit spam peut-il être aussi lent ?

À la première requête, les données d’archive, d’exploration et de page en ligne du domaine sont lues, ce qui peut prendre jusqu’à 25 secondes. Le résultat est conservé en cache pendant 24 heures (cached: true). Réglez le délai d’expiration de votre client à 30 secondes au minimum. fresh=1 ignore le cache et relance l’analyse.

Puis-je l’appeler depuis le navigateur, depuis mon propre site ?

Non. L’API n’envoie aucun en-tête CORS et rejette les requêtes de navigateur provenant d’autres sites. Placer votre clé dans le code du navigateur ne serait de toute façon pas sûr ; effectuez l’appel depuis votre propre serveur. Le volet Essayer de cette page fait exception, car il s’exécute depuis la même adresse.

J’ai perdu ma clé.

La clé ne peut pas être récupérée ; seule son empreinte est conservée. Créez une nouvelle clé, mettez à jour votre script et révoquez l’ancienne.

Comment voir ma limite ?

GET /api/v1/usage renvoie le nombre total de requêtes de votre clé et l’état de la fenêtre de la minute en cours. En mode compte, les en-têtes X-Quota-* des réponses réussies indiquent ce qu’il reste du dernier quota décompté ; le détail se trouve sur la page de votre compte.

Dans quel fuseau horaire sont les horodatages ?

Les champs de date des réponses sont en UTC (comme 2026-11-10T09:40:36.000Z). Les quotas quotidiens et mensuels sont réinitialisés selon l’heure de la Turquie (UTC+3).