Перейти к содержимому
kosto kosto API v1
OpenAPI Вернуться в панель

Kosto API · v1

Документация Kosto API:
авторитетность домена в ваших собственных инструментах.

Запрашивайте по HTTP ту же оценку авторитетности, что и в панели, а также ссылающиеся домены, сравнение рядом и проверку на спам. Все ответы приходят в JSON, имена полей записываются в snake_case, а к каждому эндпоинту ниже приложен рабочий пример.

Базовый адрес
Эндпоинт
7
Лимит в минуту
120
Формат
JSON
Авторизация
API-ключ

Оценка авторитетности

Оценка от 0 до 100, рейтинги и компоненты, из которых складывается оценка. Один домен или десять рядом.

Ссылающиеся домены

Домены, которые ссылаются на домен, отсортированы по оценке; минимальную оценку вы задаете сами.

Проверка на спам

Оценка риска и причины для признаков злоупотреблений: гемблинг, контент для взрослых, фарма, реплики.

  • Все эндпоинты находятся по адресу /api/v1. Версия входит в адрес.
  • Запросы и ответы — это JSON в кодировке UTF-8. Даты записываются в формате ISO 8601 (UTC).
  • Машиночитаемое описание: скачайте документ OpenAPI 3.1.

Начало работы

Быстрый старт

Три шага от получения ключа до первого ответа.

  1. 1

    Получите ключ

    Создайте ключ ниже. Ключ виден только в момент создания; скопируйте его и сохраните в надежном месте.

  2. 2

    Отправьте первый запрос

    Передавайте ключ в заголовке Authorization. Пример справа подготовлен на выбранном вами языке; вместо YOUR_API_KEY подставьте свой ключ.

  3. 3

    Прочитайте ответ

    Поле authority_score содержит оценку от 0 до 100. Если found равно false, домена нет в индексе ссылок; это не ошибка, возвращается 200. Поле score_source указывает тип оценки: data — основана на данных, standard и calibrated — приблизительные оценки.

С помощью панели Попробовать под каждым эндпоинтом можно отправить запрос прямо из браузера. Ключ хранится только в памяти этой вкладки, нигде не сохраняется, и запрос не уходит, пока вы не нажмете кнопку.

Начало работы

Аутентификация

Для каждого эндпоинта, кроме /api/v1/openapi.json, нужен API-ключ. Ключ начинается с op_ и состоит из 35 символов. Используйте один из двух заголовков ниже; они равнозначны.

HTTP-заголовокФормат
AuthorizationBearer op_… (регистр в Bearer не важен)
X-API-Keyop_…

Защита ключа

  • Сервер хранит не сам ключ, а его хеш SHA-256. Если вы потеряете ключ, создайте новый и отзовите старый.
  • Храните ключ в переменной окружения или в хранилище секретов. Не помещайте его в исходный код, публичные репозитории и код, который выполняется в браузере.
  • Отозванный ключ получает 403 key_revoked. Если ключа нет или его формат неверен, возвращается 401.
  • CORS-заголовок не отправляется, поэтому браузерный код с другого сайта не может читать этот API (cross_site_forbidden). Скрипты, командная строка и серверный код работают без проблем.
  • В режиме аккаунта ключ принадлежит аккаунту и учитывается по тарифу этого аккаунта; ключ приостановленного аккаунта или не привязанный ни к какому аккаунту получает 403.

Начало работы

Ограничения скорости и квоты

Действуют два отдельных ограничения: минутный лимит запросов одинаков для всех ключей, а месячные и суточные квоты зависят от вашего тарифа.

Лимит частоты: 120 запросов в минуту

Каждый ключ может сделать 120 запросов в фиксированном 60-секундном окне. Окно открывается первым запросом ключа, закрывается через 60 секунд, и счетчик обнуляется. Запросы без действительного ключа учитываются в общем окне для адреса клиента. Отклоненные запросы (например, с 401 или 400) тоже засчитываются в окно. В каждом ответе /api/v1 есть следующие заголовки:

HTTP-заголовокЗначение
X-RateLimit-LimitКоличество запросов, разрешенных в окне (120).
X-RateLimit-RemainingКоличество оставшихся запросов в текущем окне.
X-RateLimit-ResetМомент закрытия окна в секундах Unix.
Retry-AfterЧисло секунд ожидания в ответах 429 и 503.

При превышении лимита возвращается 429 rate_limited. Подождите время, указанное в заголовке Retry-After, и повторите запрос; повтор без ожидания только сильнее заполняет окно.

Квоты тарифа

В режиме аккаунта каждый вызов списывает единицу со счетчика API-запросы. Массовый запрос тратит столько строк массового запроса, сколько в нем строк, а проверка на спам тратит одну проверку на спам. Неудавшийся вызов возвращает потраченное. Повторная проверка на спам того же домена в тот же день не учитывается (кроме fresh=1).

ТарифAPI-ключЗапросов API / месяцСтрок массовых запросов / деньПроверок спама / день

Суточные и месячные квоты обновляются в полночь и в начале месяца по времени Турции (UTC+3). Когда квота исчерпана, возвращается 429 quota_exceeded; в сообщении указано, какой счетчик исчерпан, ваше использование и ваш тариф. Цены смотрите на странице тарифов.

Начало работы

Коды ошибок

Ошибки приходят с HTTP-кодом состояния и всегда с одним и тем же телом. Значение code стабильно, поэтому ваша программа должна ветвиться по нему. Поле message — описание для людей, оно может меняться; по умолчанию оно на английском, а другой язык выбирается заголовком Accept-Language или X-Kosto-Lang.

СтатусКодКогда
  • Если в ответах 5xx и 429 есть заголовок Retry-After, подождите указанное в нем время; не повторяйте ответы 4xx тем же запросом, а исправьте запрос.
  • В ответе 405 заголовок Allow сообщает, какой метод поддерживает эндпоинт. HEAD обрабатывается как GET.
  • Пока индекс ссылок загружается, запросы ссылающихся доменов могут возвращать 503 graph_unavailable; повторите запрос после Retry-After: 15.

Начало работы

Пагинация и массовые запросы

API не использует ни курсоры (cursor), ни номера страниц. Эндпоинты, возвращающие списки, отвечают одним ответом, размер которого ограничивается параметрами.

ЭндпоинтПравило
GET /backlinkslimit не больше 1000 (по умолчанию 100). Сервер сначала выбирает лучшие ссылающиеся домены по оценке, а фильтр min_score применяется среди 1000 лучших по рангу ссылок. Поэтому при использовании фильтра returned может получиться меньше limit. total — общее число ссылающихся доменов без учета фильтра.
GET /compareОт 2 до 10 доменов. Написания, ведущие на один и тот же сайт, сводятся к одной строке; после сведения должно остаться не менее двух разных сайтов.
POST /bulkНе более 1000 доменов в одном запросе, тело не больше 1 МБ. При превышении вы получите too_many_domains (400) или payload_too_large (413). Пустые строки пропускаются, один и тот же сайт сводится к одной строке, недопустимые значения остаются на месте как valid: false; порядок соответствует порядку первого появления.

Разбиение больших списков

Если доменов больше 1000, разбейте список на части по 1000 и отправляйте их по очереди. Каждая часть — отдельный запрос, который учитывается в лимите в минуту; в режиме аккаунта дополнительно расходуется квота массовых запросов по числу строк.

Прочее

Версии и журнал изменений

Версия входит в адрес: /api/v1. Поле info.version документа OpenAPI указывает версию документации этой версии API.

  • Новые эндпоинты и новые поля в ответах можно добавлять без смены версии. Мы ожидаем, что ваш клиент будет игнорировать поля, которых он не знает.
  • Несовместимые изменения, такие как смена типа или смысла существующего поля либо удаление поля, выходят в новой версии (/api/v2).
  • Тексты message могут меняться. Ориентируйтесь на значения code и HTTP-коды состояния.
  1. 1.0.0Текущая версия

    Первый выпуск. Семь эндпоинтов: domain, backlinks, compare, bulk, spam, usage и openapi.json.

    • Аутентификация по ключу: Authorization: Bearer или X-API-Key.
    • Лимит 120 запросов в минуту и заголовки X-RateLimit-*.
    • Формат ошибки: { "error": { "code", "message" } }.

Прочее

Частые вопросы

Домен не найден — это ошибка?

Нет. Для домена, которого нет в индексе ссылок, возвращается 200 и found: false. В этом случае subdomains и referring_domains равны null. А недопустимое значение (текст, не являющийся доменом) возвращает 400 invalid_domain.

Могу ли я отправить URL?

Да. Параметр domain принимает домен или URL. https://www.primer.ru/page в ответе становится primer.ru. То же относится к bulk и compare.

Почему число ссылающихся доменов иногда равно null?

referring_domains равно null, если домена нет в графе ссылок или граф в данный момент не может ответить. Пока граф не готов, backlinks возвращает 503 graph_unavailable.

Оценка приблизительная или основана на данных?

Смотрите поле score_source. Если там data, оценка рассчитана по измеренным данным о ссылках и трафике; в панели она отмечена значком на основе данных и закрашенной точкой. standard и calibrated — приблизительные оценки; в панели они получают значок приблизительно и пустую точку. Когда приходят score_low и score_high, они задают ожидаемый диапазон оценки, и панель рисует его дугой на циферблате. Если оба равны null, диапазон не сообщается; это не означает диапазон нулевой ширины.

Почему количество ссылающихся доменов на панели может отличаться от того, что в API?

referring_domains — это всегда число ссылающихся доменов, учтенных в индексе ссылок, а эндпоинт backlinks перечисляет эти домены по именам. В заголовке панель показывает одно число: количество по данным поиска, если для домена открыты данные поиска, и количество по индексу ссылок, если не открыты. Когда в заголовке стоит число по данным поиска, число по индексу ссылок указано в подробностях под карточкой как число доменов, которые «мы можем перечислить по именам». Эти два числа измеряются разными методами, и одно не опровергает другое.

Почему проверка на спам может работать так медленно?

При первом запросе считываются архивные данные, данные краулера и данные живой страницы домена; это может занять до 25 секунд. Результат хранится в кэше 24 часа (cached: true). Установите в клиенте тайм-аут не менее 30 секунд. Параметр fresh=1 пропускает кэш и сканирует заново.

Можно ли вызывать API из браузера, с моего сайта?

Нет. API не отправляет CORS-заголовок и отклоняет браузерные запросы с других сайтов. Ключ в коде браузера все равно небезопасен; делайте вызов со своего сервера. Панель «Попробовать» на этой странице — исключение, так как работает с того же адреса.

Я потерял ключ.

Ключ восстановить нельзя: хранится только его хеш. Создайте новый ключ, обновите скрипт и отзовите старый.

Как посмотреть свой лимит?

GET /api/v1/usage возвращает общее число запросов вашего ключа и состояние текущего минутного окна. В режиме аккаунта заголовки X-Quota-* в успешных ответах показывают остаток квоты, учтенной последней; подробности есть на странице вашего аккаунта.

В каком часовом поясе указаны метки времени?

Поля с датами в ответах указаны в UTC (например, 2026-11-10T09:40:36.000Z). Суточные и месячные квоты обновляются по времени Турции (UTC+3).