Документация API Expired Domains

Единый REST API с JSON-ответами для доменной аналитики: SEO-метрики (TF, CF, DA, DR, Age, Backlinks, Traffic и т.д.), история Wayback Machine, 400 000+ новых доменов каждый день, 30+ источников данных о доменах и 90+ фильтров для точного поиска. Включает live-аукционы, expired-домены, полные отчеты, избранное, проверки доступности, Karma Metric и данные профиля. Bearer-ключ Pro, 60 запросов в минуту.

Попробуйте бесплатно!
Используй бонусные кредиты!
Открыть таблицу доменов
+5

Public API Karma.Domains предоставляет программный доступ к отчетам по доменам: auctions, expired, backorder и buy-now. Все ответы — JSON по HTTPS. Базовый URL: https://api.karma.domains, префикс маршрутов: /v1.

Karma.Domains — это платформа доменной аналитики для инвесторов, SEO-команд и конвейеров автоматизации:

  • 400 000+ новых доменов ежедневно в процессах обнаружения и мониторинга (всего 7 000 000+ доменов)
  • 30+ источников данных о доменах в целом, включая 27+ источников auction/expired/backorder/buy-now (GoDaddy, NameJet, DropCatch, Dynadot, GNAME, Namecheap и т.д.)
  • 90+ фильтров для точного поиска по качеству домена, SEO, истории контента и аукционным сигналам (TF, CF, DA, DR, Age, Backlinks, Traffic, Keywords, Anchor Text и т.д.)
  • Покрытие TLD и ccTLD (например .com, .net, .org, .biz, .info, .at, .be, .ca, .cc, .cl, .co, .co.nz)
  • SEO- и авторитетные данные от крупных поставщиков: Ahrefs, Majestic, Moz, SimilarWeb
  • Исторический контент и сигналы изменений через Wayback Machine

Схемы запросов и ответов (поля фильтров, структура отчета, enum сортировки) — в интерактивной документации: Swagger UI или ReDoc.
Эта страница — обзор интеграции: аутентификация, лимиты, список эндпоинтов, типовые сценарии и примеры.

Введение

Public API предназначен для скриптов, внутренних дашбордов, CRM-систем и любой автоматизации, которой нужны те же данные, что и в веб-приложении Karma.Domains.

  • Формат: JSON
  • Версия API: 1.0.0
  • Базы: auctions, expired, backorder, buynow; поиск сразу по всем — POST /v1/reports/search (то же самое, что таблица “all databases” в UI)
  • Документация полей: только в OpenAPI
  • Доступно только на тарифе Pro и выше

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

Каждый запрос должен включать заголовок:

Authorization: Bearer YOUR_API_KEY

Как получить API-ключ

  1. Тариф Pro (без Pro API недоступен).
  2. Profile → Settings — создайте или сбросьте ключ в разделе API key.

Тот же ключ используется для MCP server (AI-ассистенты). Лимит запросов общий между REST и MCP.

Типичные ответы, когда ключ неверный

Code Reason
401 Отсутствует заголовок, недействительный ключ или опечатка в Bearer
403 Ключ валидный, но у аккаунта нет активного Pro (Pro plan required for API access)

Всегда отправляйте Accept: application/json.

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

  • 60 запросов в минуту на API-ключ
  • Окно: 60 секунд
  • Счетчик общий для всех эндпоинтов Public API и MCP

Успешные ответы содержат заголовки:

Header Description
X-RateLimit-Limit Лимит (60)
X-RateLimit-Remaining Запросов осталось в текущем окне
X-RateLimit-Reset Unix timestamp, когда окно будет сброшено

Когда лимит превышен: 429 Too Many Requests и заголовок Retry-After (секунды до повторной попытки).

Советы: используйте page_size до 50 для списков; не опрашивайте POST /search чаще, чем нужно — ответы кэшируются (см. “Caching”).

Дневная квота строк

  • 50 000 строк списка в сутки на аккаунт (API-ключ / авторизованный пользователь)
  • Сброс: полночь UTC
  • Счётчик общий для list-эндпоинтов Public API, list-инструментов MCP, таблиц в web UI и CSV export

Каждый list-запрос списывает page_size строк (запрошенный размер страницы, не total_count).

Успешные list-ответы содержат заголовки:

Header Description
X-Quota-Limit Дневной лимит (50000)
X-Quota-Remaining Строк осталось сегодня
X-Quota-Reset Unix timestamp сброса дневной квоты

При превышении: 429 Too Many Requests и Retry-After (секунды до сброса).

Глубина пагинации: для одного поиска/фильтра page × page_size не должно превышать 5000 (например, при page_size=50 макс. страница — 100). Это ограничивает глубокую выкачку одного результата; дневная квота ограничивает суммарный объём по всем запросам.

Обзор эндпоинтов

Полные параметры query/body — в OpenAPI.

Method Path Purpose
POST /v1/reports/search Поиск отчетов по body ReportListFilterSchema, пагинация, сортировка
GET /v1/reports/favorites Список избранных отчетов текущего пользователя
POST /v1/reports/favorites Добавить отчет в избранное
DELETE /v1/reports/favorites/{report_type}/{report_id} Удалить из избранного
GET /v1/reports/by-domain/{domain} Найти ID отчетов по точному имени домена
GET /v1/reports/{report_type}/{report_id} Полный отчет по типу базы и id отчета
GET /v1/reports/check/expired/{report_id} Проверить, дропнулся ли домен для отчета expired
GET /v1/user Профиль пользователя (PublicUserProfileSchema)
GET /v1/domains/checker/expiry/{domain} Live-проверка: доступен ли домен для регистрации
GET /v1/domains/checker/karma_metric/{domain} Live-расчет Karma Metric через WayBack Machine

Справочник параметров моделей

Ниже — практическая карта параметров для 3 ключевых моделей OpenAPI, которые определяют большую часть возможностей API.

ReportListFilterSchema (тело запроса для POST /v1/reports/search)

Семантика значений, используемая в этой схеме:

  • null или пропущенное поле = фильтр не применяется.
  • Строковые поля запроса поддерживают , для AND и | для OR там, где это задокументировано.
  • Диапазоны дат — это массивы из 2 строк: [from, to].
  • Для большинства диапазонов оценок используются включающие *_min / *_max.
Parameter Type Description
domain string | null Фильтр по подстроке домена, без учета регистра. , = AND (все термины должны совпасть), | = OR (любой термин). Макс. длина: 350.
tlds string | null Список TLD, разделенный запятой или пробелом (например, .com .net .org). Макс. длина: 350.
domain_type string[] | null Допустимые значения: auctions, backorder, buynow, expired. OR-логика между выбранными значениями.
favorites boolean | null true = только избранное, false = исключить избранное. Требует контекст аутентифицированного пользователя.
categories string[] | null OR-логика по категориям, поддерживает формат Category / Subcategory, поиск по подстроке без учета регистра.
languages string Запрос языков с , (AND) / | (OR), поиск по подстроке без учета регистра. Макс. длина: 350.
keywords string | null Поиск в контенте Wayback (title, description, h1-h6 и т.д.). , = AND, | = OR. Макс. длина: 350.
website_ids string[] Идентификаторы вроде GA/Metrika для поиска доменов с тем же владельцем.
domain_length_min / domain_length_max integer | null Границы длины домена (задокументировано как 1..30).
domain_numbers / domain_hyphens boolean Требовать/исключать цифры и дефисы в имени домена.
report_added_time string[2] | null Диапазон дат: ["YYYY-MM-DD","YYYY-MM-DD"]. Бэкенд автоматически применяет границы начала/конца дня.
karmascore_min / karmascore_max integer | null Границы KarmaScore, 0..100.
karmametric_min / karmametric_max integer | null Границы Karma Metric, 0..100.
brandscore_min / brandscore_max integer | null Границы Brandscore, 0..100.
openpagerank_min / openpagerank_max integer | null Границы Open PageRank, задокументированы как 0..10.
ahrefs_dr_min / ahrefs_dr_max number | null Границы Ahrefs DR, 0..100.
ahrefs_ur_min / ahrefs_ur_max number | null Границы Ahrefs UR, 0..100.
ahrefs_ar_min / ahrefs_ar_max integer | null Границы Ahrefs Rank (>= 0).
majestic_tf_min / majestic_tf_max integer | null Границы Majestic TF, 0..100.
majestic_cf_min / majestic_cf_max integer | null Границы Majestic CF, 0..100.
majestic_bl_min / majestic_bl_max integer Границы backlinks Majestic.
majestic_rd_min / majestic_rd_max integer Границы referring domains Majestic.
majestic_topics / majestic_lang string[] / string Фильтры тематик и языка анкоров.
moz_da_min / moz_da_max integer | null Границы Moz DA, 0..100.
moz_ss_min / moz_ss_max integer | null Границы Moz Spam Score, 0..100.
moz_bl_min / moz_bl_max integer Границы backlinks Moz.
moz_rd_min / moz_rd_max integer Границы referring domains Moz.
moz_bl_url / moz_bl_anchor string Фильтры URL / анкор-фразы обратных ссылок Moz.
sw_visits_min / sw_visits_max integer Границы визитов SimilarWeb.
sw_last_traffic_date string[2] | null Диапазон месяцев SimilarWeb: ["YYYY-MM","YYYY-MM"].
sw_country_filters object[] Фильтры доли стран (country, опционально share_min).
sw_ts_direct_min...sw_ts_social_max number | null Границы долей каналов источников трафика SimilarWeb, 0..100.
wa_age_min / wa_age_max integer | null Возраст домена по Wayback в годах.
wa_first_snap / wa_last_snap string[2] | null Диапазон дат: ["YYYY-MM-DD","YYYY-MM-DD"] для окон первого/последнего снимка.
wa_changes_min/max, wa_redirects_min/max, wa_parkings_min/max integer Счетчики истории Wayback.
wa_hieroglyphs, wa_redirects, wa_error403 boolean Флаги качества контента Wayback.
wa_lang_filters object[] Фильтры языков Wayback (language, опционально ratio_min).
wa_server_code, wa_server_code_ratio_min/max integer | null / number | null Фильтр server code Wayback (например, 200, 301, 302, 403, 404) + границы ratio 0..100.
ke_etv_min/max, ke_total_min/max integer Границы трафиковой ценности / количества ключей Keywords Everywhere.
ke_keyword string Фильтр фразы Keywords Everywhere.
google_has_index, google_has_mentions boolean | null Семантика true/false/unset для требования индексации или упоминаний в Google SERP.
google_title_index/mentions, google_description_index/mentions string Фильтры фраз title/description в сниппетах SERP.
trustpilot_rating_min/max, trustpilot_reviews_count_min/max number | null / integer | null Границы рейтинга Trustpilot (0..5) и количества отзывов.
trustpilot_category string Фильтр фразы категории Trustpilot.
auction_source string[] | null Названия источников аукциона (без учета регистра) или составное значение `source
auction_end_time, auction_added_time string[2] | null Диапазон дат: ["YYYY-MM-DD","YYYY-MM-DD"].
auction_price_min/max number Границы цены аукциона.
auction_bids_min/max integer Границы количества ставок аукциона.
combine_seo object | null Кросс-вендорный CombineSEOFilter: authority/backlinks/refdomains/traffic/keywords/backlink-url/anchors, с OR-логикой вендоров в каждой строке и AND между строками.

ReportListResponseSchema (ответ для POST /search и GET /favorites)

Parameter Type Description
report_list ReportItem[] Пагинированные строки для табличного вида и формирования shortlist.
total_count integer Общее количество совпавших записей для текущего фильтра.

Поля уровня строки в report_list[] (из ReportItem) включают:

Parameter Type Description
report_id string Стабильный идентификатор отчета (используется для полного отчета и избранного).
report_type string Одно из: auctions, expired, backorder, buynow.
domain, domain_tld string Имя домена и TLD.
added_at, updated_at integer Timestamp-ы.
processed, demo, is_expired boolean Флаги состояния, используемые в workflow UI/API.
karmascore, karmametric, brandscore integer Ключевые метрики качества/брендируемости.
ahrefs_dr, ahrefs_ur number Сводные метрики Ahrefs.
majestic_tf/cf/bl/rd, moz_da/ss/bl/rd integer Сводные метрики Majestic и Moz.
ke_etv, ke_total integer Сводные значения Keywords Everywhere.
sw_last_traffic, sw_country_share, sw_sources integer/object Сводки трафика SimilarWeb.
wa_age, wa_last_snap, wa_changes, wa_langs, wa_server_code integer/array Сводные сигналы Wayback.
google_index, trustpilot_rating, trustpilot_reviews_count boolean/number/integer Сводные поля Google/Trustpilot.
auctions array/object Сводка аукционных записей, если доступна.

ReportFullResponseSchema (ответ для GET /v1/reports/{report_type}/{report_id})

Parameter Type Description
report_id, report_type, domain, domain_tld string Ключевые поля идентификации.
domain_length, domain_numbers, domain_hyphens integer/boolean Атрибуты структуры домена.
favorite, demo, processed, is_expired boolean Состояние отчета и пользовательские флаги.
added_at, updated_at, created_at, checked_at, expire_checked_at integer Timestamp-ы жизненного цикла.
providers_status object Карта статуса обработки по провайдерам (строковые значения).
web_archive object Данные Wayback Machine — разбор ниже.
metrics DomainMetrics Вложенные SEO/трафик/репутация-метрики — разбор ниже.
auctions object | null Аукционные лоты, сгруппированные по end_time — разбор ниже.

metrics → DomainMetrics

Большинство блоков провайдеров могут быть объектом с данными, false (не загружено) или null. categories и blacklists также могут быть [], если пусто.

Parameter Type Description
openpagerank number | integer | boolean | null Оценка Open PageRank (обычно 0..10), когда доступна.
categories CategoryData[] | boolean | null Категории контента от провайдеров классификации.
blacklists BlacklistsData[] | boolean | null Попадания в blacklist по безопасности/репутации.
ahrefs AhrefsData | boolean | null Метрики домена Ahrefs.
majestic MajesticData | boolean | null Majestic Trust/Citation Flow и профиль обратных ссылок.
moz MozData | boolean | null Moz authority, spam score и детали обратных ссылок.
keywordseverywhere KeywordseverywhereData | boolean | null Оценки трафика/ключей Keywords Everywhere.
similarweb SimilarWebData | boolean | null SimilarWeb visits, sources и геодолями.
brandscore BrandscoreData | boolean | null Компоненты оценки брендируемости.
karma_metric KarmaMetricData | boolean | null Оценка Karma Metric из истории Wayback.
trustpilot TrustpilotData | boolean | null Рейтинг Trustpilot и статистика отзывов.
google GoogleData | boolean | null Google index и сниппеты упоминаний в SERP.
ai_summary string | null AI-сгенерированный текстовый summary домена.

AhrefsData

Parameter Type Description
domain_rating number | null Ahrefs DR.
url_rating number | integer | null Ahrefs UR.
ahrefs_rank integer | null Ahrefs Rank (меньше = сильнее).

MajesticData

Parameter Type Description
tf, cf integer | null Trust Flow / Citation Flow (0..100).
backlinks, refdomains integer | null Количество backlinks и referring domains.
primary_topic string | null Основная тематическая категория.
topics array | null Список распределения тематик.
anchor_lang array | null Распределение языков anchor text.
indexed_urls, referring_ips, referring_subnets integer | null Счетчики индекса и сетевого разнообразия.

MozData

Parameter Type Description
moz_domain_authority integer | null Moz DA.
moz_spam_score integer | null Moz Spam Score.
page_rank, moz_link_propensity number | integer | null Legacy rank и склонность к ссылочности.
moz_*_to_subdomain fields integer | null Счетчики графа ссылок Moz (pages/domains, follow/nofollow/redirect/deleted).
moz_da_history_values string | null Сериализованные значения истории DA.
backlinks MozBacklink[] | null Строки backlinks (domain_source, url_source, domain_target, url_target, anchor_text, harmonic_centrality, last_found_date).

KeywordseverywhereData

Parameter Type Description
etv integer | null Оценочная ценность трафика.
total_keywords integer | null Общее количество отслеживаемых ключей.
data KeywordItem[] | null Строки ключей (position, etv, keyword).

SimilarWebData

Parameter Type Description
estimated_monthly_visits object | null Карта месяц → визиты.
traffic_sources TrafficSources | null Доли каналов: Social, Paid Referrals, Mail, Referrals, Search, Direct (отношения 0..1).
top_country_shares CountryShare[] | null Геораспределение (Country, CountryCode, Value).
engagments Engagements | null BounceRate, PagePerVisit, Visits, TimeOnSite, Month, Year.
category string | null Категория сайта SimilarWeb.

BrandscoreData

Parameter Type Description
pronounceability, memorability, uniqueness, appeal, brandscore integer Компоненты брендируемости и итоговая оценка.

KarmaMetricData

Parameter Type Description
karma_metric integer Итоговая оценка, 0..100.
components KarmaMetricComponents A_mass, A_cont, A_stab, A_trend (каждый 0..100).
period string | null Период в формате YYYY-MM (или null, если недоступно).

TrustpilotData

Parameter Type Description
rating number | null Рейтинг, обычно 0..5.
reviews_count integer | null Количество отзывов.
category string | null Бизнес-категория Trustpilot.

GoogleData

Parameter Type Description
google_index GoogleItem[] | null Проиндексированные страницы для site:domain (rank, url, title, description).
google_mentions GoogleItem[] | null Результаты упоминаний для поисков с доменом в кавычках.

CategoryData / BlacklistsData

Model Key fields
CategoryData categories[], vendor, info_url
BlacklistsData vendor, info_url, optional info

web_archive (payload Wayback Machine)

Объект с тремя основными блоками: info, ts_summary, history. В ответах полного отчета history возвращается в порядке от новых к старым.

Parameter Type Description
info object | null Сводка покрытия архива для домена.
ts_summary object | null Агрегированные сигналы KarmaScore / Wayback, используемые в табличных фильтрах.
history array Таймлайн снимков (один объект на каждый capture Wayback).

web_archive.info

Parameter Type Description
snap_counter integer Общее количество учтенных снимков Wayback.
years_counter integer Количество лет с активностью в архиве (сигнал возраста домена).
first_ts integer Unix timestamp первого снимка.
last_ts integer Unix timestamp последнего снимка.
years object Карта год → количество снимков по месяцам (данные sparkline/calendar).

web_archive.ts_summary

Parameter Type Description
average_karma_score integer Средний KarmaScore, 0..100 (соответствует полю списка karmascore).
wa_changes integer Количество значимых изменений контента в сканированной истории.
wa_langs array Строки распределения языков: language, pageRatio (0..100).
wa_server_code array Распределение HTTP-кодов: server_code (например, 200, 301, 403), response_ratio (0..100).
wa_tags array Обнаруженные теги контента по истории.
pattern_shares array Строки долей паттернов: factor, description, share.
chart_data array Точки временного ряда: timestamp, karma_score, lang, server_code, tags, detected_patterns.

web_archive.history[] (строка снимка)

Parameter Type Description
snaped_at integer Unix timestamp снимка.
webarchive_link string | null URL Wayback для этого capture (null у закрывающего placeholder-снимка).
headers object | null HTTP-метаданные, обычно status_code (200, 301, 302, 403, 404, 429, …), original_url.
screenshot boolean | null true, если screenshot существует (бинарные данные хранятся отдельно; получение через screenshot API в UI).
content_info object | null Распарсенный контент страницы (см. ниже).
karma_score object | null Оценка на снимок: score (0..100), detected_patterns, tags (флаги porno/crypto/gambling/…).
redirects array | null Данные цепочки редиректов, когда есть.
website_ids array | null Обнаруженные site IDs (name, website, ids[]), например analytics tags.
built_with object | null Данные детекта технологического стека (когда доступны).

web_archive.history[].content_info

Parameter Type Description
lang string | null Обнаруженный код языка страницы.
title, description, keywords string | null Поля meta / текста страницы, используемые в фильтрах и UI.
generator, author, copyright string | null Дополнительные meta-поля.
h1 … h6 string[] | null Тексты заголовков (по ним ищет фильтр keywords).
cloud_words array | null Элементы облака слов (word).
external_links, internal_links array | null Списки внешних/внутренних ссылок.
rel_canonical, meta_robots string | null Canonical URL и meta robots.
length_symbols, length_words integer Счетчики размера контента.

auctions (аукционные лоты)

Присутствует, когда у отчета есть данные аукциона (auctions, и иногда связанные строки в других базах).
В ответах полного отчета лоты сгруппированы по времени завершения:

{
  "1764441900": [
    { "source": "godaddy", "sale_type": "auction", "price": 120, "bids": 3, "...": "..." }
  ]
}
  • Ключ объекта = end_time (Unix seconds).
  • Значение = массив объектов лотов, завершающихся в это время (несколько платформ могут иметь один ключ).
Parameter Type Description
source string Источник платформы/регистратора аукциона (например, godaddy, namejet, dynadot, dropcatch, sedo, sav.com). Без учета регистра в фильтрах.
sale_type string Тип листинга (например, auction, buynow, Closeout, Pre-Release, Dropped).
domain string Имя домена лота.
item_id string Идентификатор лота/листинга на платформе.
end_time integer Время окончания лота (Unix seconds); также используется как ключ группировки в полном отчете.
price number Текущая цена (обычно USD).
bids integer | null Количество ставок, если применимо.
currency string Символ/код валюты (по умолчанию "$").
report_type string Владельческая база: auctions, backorder или buynow.
priority integer Внутренний вес сортировки/приоритета (по умолчанию 0).

Совет по фильтру: auction_source в поиске принимает обычный источник (godaddy) или составное значение source|sale_type (например, godaddy|auction).

Для точных ограничений полей (nullable-правила, enum-значения, min/max, вложенные объекты) всегда используйте OpenAPI или ReDoc.

Параметр report_type

Для полного отчета и избранного: auctions, expired, backorder, buynow.
Значение all используется только в логике поиска (все базы), а не как {report_type} в path.

Пагинация и сортировка (list endpoints)

Query-параметры:

Parameter Default Description
page 1 Номер страницы
page_size 10 Размер страницы (макс. 50)
sort_by added_at Имя колонки сортировки (как в UI-таблице; enum в OpenAPI)
sort_desc true true — по убыванию

Лимит глубины: page × page_size ≤ 5000. Запросы глубже возвращают 422 (ошибка валидации).

Домены в URL

Для {domain} в пути используйте percent-encoding (IDN, кириллица и т.д.). Сервер нормализует имя (punycoded/lowercase).

Типовые сценарии

1. Поиск → полный отчет

  1. POST https://api.karma.domains/v1/reports/search с телом фильтра (см. OpenAPI → ReportListFilterSchema).
  2. Из report_list[] возьмите report_id и report_type.
  3. GET https://api.karma.domains/v1/reports/{report_type}/{report_id}.

Фильтры соответствуют фильтрам в веб-UI — удобно сверять с UI; схему полей смотрите в OpenAPI.

2. Точный домен без долгого поиска

  1. GET /v1/reports/by-domain/example.com
  2. В ответе matches[] — до одной записи на каждую базу, где домен существует.
  3. Выберите нужный report_type → GET /v1/reports/{report_type}/{report_id}.

Если matches пустой — домен отсутствует в базах Karma.

3. Избранное

  • Только список: GET /v1/reports/favorites
  • Тот же список через поиск: POST /v1/reports/search с "favorites": true в теле
  • Добавить: POST /v1/reports/favorites с {"report_id": "...", "report_type": "expired"}
  • Удалить: DELETE /v1/reports/favorites/expired/{report_id}

4. Проверка дропа (expired report)

GET /v1/reports/check/expired/{report_id} — id отчета, а не имя домена.

  • При успешной проверке обновляет запись отчета на сервере
  • is_expired: true — домен вероятно доступен для регистрации (не “WHOIS expiry date passed”)
  • Повторять live проверку для того же отчета — не чаще одного раза в 3 часа (business rule)
  • HTTP-ответ кэшируется 1 час для повторных GET с тем же report_id (см. “Caching”)

5. Проверка домена без отчета в базе

GET /v1/domains/checker/expiry/{domain} — live WHOIS/DNS; не меняет отчет в базе.

  • available: true — вероятно можно зарегистрировать
  • available: false — занят или зарезервирован
  • Повторный запрос того же домена в пределах ~1 часа может вернуть кэшированный ответ

6. Karma Metric на лету

GET /v1/domains/checker/karma_metric/{domain} — Karma Metric из WayBack Machine; не обновляет отчет. Поля ответа — OpenAPI (KarmaMetricData). Кэш ответа на домен — ~1 час.

Подробнее о Karma Metric в блоге

7. Баланс и тариф

GET /v1/user — email, balance (кредиты), флаги тарифа, данные подписки. API-ключ в ответ не включается. Ответ кэшируется ~1 минуту на ключ — не опрашивайте чаще, чем нужно для актуального баланса.

Caching

На уровне Public API кэшируется HTTP response body. Некоторые эндпоинты используют early refresh (фоновое обновление до истечения TTL: 4 мин для TTL 5 мин, 50 мин для TTL 1 ч).

Endpoint TTL
POST /v1/reports/search 5 min
GET /v1/reports/favorites 5 min
POST /v1/reports/favorites none
DELETE /v1/reports/favorites/{report_type}/{report_id} none
GET /v1/reports/by-domain/{domain} 5 min
GET /v1/reports/check/expired/{report_id} 1 h
GET /v1/reports/{report_type}/{report_id} none
GET /v1/user 1 min
GET /v1/domains/checker/expiry/{domain} 1 h
GET /v1/domains/checker/karma_metric/{domain} 1 h

POST/DELETE избранного сразу меняют данные на сервере, но повторный GET /favorites или POST /search с favorites: true может вернуть устаревший список до истечения кэша (5 мин).

Примеры запросов (curl)

Замените YOUR_API_KEY на ключ из вашего профиля. Базовый URL: https://api.karma.domains.

Поиск expired с фильтром

curl -X POST "https://api.karma.domains/v1/reports/search?page=1&page_size=25&sort_by=added_at&sort_desc=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "karmascore_min": 60,
    "domain_type": ["expired"]
  }'

Тело фильтра — любые поля из ReportListFilterSchema в OpenAPI.

Полный отчет

curl "https://api.karma.domains/v1/reports/expired/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Поиск по домену

curl "https://api.karma.domains/v1/reports/by-domain/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Добавить в избранное

curl -X POST "https://api.karma.domains/v1/reports/favorites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "report_id": "507f1f77bcf86cd799439011",
    "report_type": "expired"
  }'

Проверка доступности домена

curl "https://api.karma.domains/v1/domains/checker/expiry/mybrand.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Karma Metric

curl "https://api.karma.domains/v1/domains/checker/karma_metric/mybrand.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Сценарии интеграции

Ночной pipeline отбора expired

Ежедневный cron: POST /search с сохраненным JSON-фильтром (как saved filter в UI), пагинация с page_size=50, экспорт report_id в вашу БД. Детальный анализ — GET полного отчета только для shortlist.

Мониторинг списка имен перед регистрацией

Очередь доменов → GET /domains/checker/expiry/{domain} → ветвление по available. Не требует наличия отчета в Karma.Domains.

Синхронизация избранного с внутренней CRM

Периодический GET /favorites; по действию пользователя в CRM — POST/DELETE избранного. Учитывайте кэш списка ~5 мин.

BI / воронковая аналитика

Экспортируйте страницы поиска, агрегируйте total_count и метрики из report_list без открытия UI. Схема строк списка — ReportListResponseSchema в OpenAPI.

MCP + скрипты на одном ключе

Команда использует MCP в Cursor для ad-hoc поиска и Public API для стабильного ETL. Общий лимит 60 запросов в минуту — планируйте батчи и backoff на 429.

MCP и Public API

Public API (REST) MCP
Audience Разработчики, скрипты, ETL AI-ассистенты (Cursor, Claude)
Interface HTTP + JSON Диалог, инструменты
Docs Эта страница + OpenAPI /ru/expired-domains-mcp/
Data Те же отчеты и базы То же
Key & limit Общий Общий

Для новых кодовых интеграций начинайте с REST. Для чат-экспериментов — MCP.

FAQ

Где полный справочник полей фильтра?

OpenAPI, схема ReportListFilterSchema. Значения полей совпадают с help по фильтрам в UI.

В чем разница между available и is_expired?

Оба в контексте API означают: домен вероятно доступен к регистрации.
available — live-проверка по имени (/domains/checker/expiry).
is_expired — проверка, привязанная к отчету базы expired (/reports/check/expired/{report_id}).

Почему 403 при корректном ключе?

Нет активного тарифа Pro. Проверьте подписку в профиле.

Почему ответ API не совпадает с UI или только что выполненным действием?

HTTP-кэш Public API — см. таблицу в разделе “Caching”. Учитывайте TTL при синхронизации с UI.

Какие значения sort_by допустимы?

Список enum в OpenAPI — названия колонок таблицы отчетов в веб-приложении.

Нужна ли эта страница, если есть OpenAPI?

OpenAPI — источник истины по типам и полям. Эта страница добавляет контекст: лимиты, кэш, порядок вызовов, use cases и подводные камни, которых нет в схеме.

Можно ли выкачать всю базу через API?

Нет. Один поиск ограничен глубиной пагинации 5000 строк, а аккаунт может получить не более 50 000 list-строк в сутки (UTC) суммарно через API, MCP и UI. Сужайте фильтры; полные отчёты — по одному домену через GET /reports/{report_type}/{report_id}.

Есть ли sandbox?

Отдельного sandbox нет; используйте Pro-аккаунт и соблюдайте rate limits. Для отладки хорошо подходят GET /user и узкий POST /search со строгим фильтром.

Коды ошибок

Code Meaning
200 Success
401 Unauthorized (key)
403 No Pro
404 Report or resource not found
422 Ошибка валидации body/query (invalid filter, sort_by, …)
429 Превышен лимит запросов или дневная квота строк
503 Лимитер или сервис квоты строк временно недоступен

Тело ошибки обычно содержит detail (строка или массив объектов валидации). Пример:

{
  "detail": "Invalid API key"
}

Полезные ссылки

Попробуйте бесплатно!

Используй бонусные кредиты!

Открыть таблицу доменов
+5