Документація 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

Схеми request і response (поля фільтрів, структура звіту, 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.

Rate limiting

  • 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”).

Daily row quota

  • 50,000 list rows per day per account (API key / signed-in user)
  • Reset: UTC midnight
  • Counter is shared across Public API list endpoints, MCP list tools, web UI tables, and CSV export

Each list request charges page_size rows (the requested page size, not total_count).

Successful list responses include headers:

Header Description
X-Quota-Limit Daily limit (50000)
X-Quota-Remaining Rows left today
X-Quota-Reset Unix timestamp when the daily quota resets

When the quota is exceeded: 429 Too Many Requests and Retry-After (seconds until reset).

Pagination depth: for a single search/filter, page × page_size must not exceed 5000 (e.g. with page_size=50, max page is 100). This limits deep scraping of one result set; the daily quota caps total volume across all queries.

Огляд ендпоінтів

Повні параметри 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} Повний звіт за типом бази і report 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 (request body для POST /v1/reports/search)

Семантика значень у цій схемі:

  • null або пропущене поле = без фільтра.
  • Строкові поля запиту підтримують , для AND та | для OR там, де це задокументовано.
  • Діапазони дат — це масиви з 2 рядків: [from, to].
  • Більшість діапазонів score використовують включні *_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[] ID на кшталт GA/Metrika для пошуку доменів із тим самим owner.
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"]. Backend автоматично застосовує межі початку/кінця дня.
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 Фільтри topics і мови anchor.
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 Фільтри Moz backlink URL / anchor phrase.
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"] для вікон першого/останнього snapshot.
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 Межі traffic value / keywords для Keywords Everywhere.
ke_keyword string Фільтр фрази Keywords Everywhere.
google_has_index, google_has_mentions boolean | null Семантика true/false/unset для вимоги індексації або mention у Google SERP.
google_title_index/mentions, google_description_index/mentions string Фільтри фраз для title/description у SERP snippets.
trustpilot_rating_min/max, trustpilot_reviews_count_min/max number | null / integer | null Межі rating Trustpilot (0..5) і кількості reviews.
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 (response для 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 Ключові метрики якості/brandability.
ahrefs_dr, ahrefs_ur number Ahrefs summary метрики.
majestic_tf/cf/bl/rd, moz_da/ss/bl/rd integer Majestic і Moz summary метрики.
ke_etv, ke_total integer Summary значення Keywords Everywhere.
sw_last_traffic, sw_country_share, sw_sources integer/object Summary трафіку SimilarWeb.
wa_age, wa_last_snap, wa_changes, wa_langs, wa_server_code integer/array Summary сигнали Wayback.
google_index, trustpilot_rating, trustpilot_reviews_count boolean/number/integer Summary поля Google/Trustpilot.
auctions array/object Summary аукціонних записів за наявності.

ReportFullResponseSchema (response для 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 Мапа статусу обробки по provider-ах (string values).
web_archive object Дані Wayback Machine — див. розбір нижче.
metrics DomainMetrics Вкладені SEO/трафік/репутація метрики — див. розбір нижче.
auctions object | null Аукціонні лоти, згруповані за end_time — див. розбір нижче.

metrics → DomainMetrics

Більшість provider-блоків можуть бути об'єктом із даними, false (не завантажено) або null. categories і blacklists також можуть бути [], якщо порожні.

Parameter Type Description
openpagerank number | integer | boolean | null Оцінка Open PageRank (зазвичай 0..10), якщо доступна.
categories CategoryData[] | boolean | null Категорії контенту від provider-ів класифікації.
blacklists BlacklistsData[] | boolean | null Потрапляння у security/reputation blacklists.
ahrefs AhrefsData | boolean | null Ahrefs доменні метрики.
majestic MajesticData | boolean | null Majestic Trust/Citation Flow і профіль backlinks.
moz MozData | boolean | null Moz authority, spam score і деталі backlinks.
keywordseverywhere KeywordseverywhereData | boolean | null Оцінки трафіку/keywords від Keywords Everywhere.
similarweb SimilarWebData | boolean | null SimilarWeb visits, sources і geo share.
brandscore BrandscoreData | boolean | null Компоненти оцінки brandability.
karma_metric KarmaMetricData | boolean | null Оцінка Karma Metric з історії Wayback.
trustpilot TrustpilotData | boolean | null Rating Trustpilot і статистика reviews.
google GoogleData | boolean | null Google index і mention SERP snippets.
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 Основна topic-категорія.
topics array | null Список розподілу topics.
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 і link propensity.
moz_*_to_subdomain fields integer | null Лічильники Moz link graph (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 Оцінний traffic value.
total_keywords integer | null Загальна кількість відстежуваних keywords.
data KeywordItem[] | null Рядки keywords (position, etv, keyword).

SimilarWebData

Parameter Type Description
estimated_monthly_visits object | null Мапа month → visits.
traffic_sources TrafficSources | null Частки каналів: Social, Paid Referrals, Mail, Referrals, Search, Direct (ratio 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 Компоненти brandability та фінальний score.

KarmaMetricData

Parameter Type Description
karma_metric integer Фінальний score, 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 Rating, зазвичай 0..5.
reviews_count integer | null Кількість reviews.
category string | null Бізнес-категорія Trustpilot.

GoogleData

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

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 Summary покриття архіву для домену.
ts_summary object | null Агреговані сигнали KarmaScore / Wayback для табличних фільтрів.
history array Timeline snapshot-ів (по одному об'єкту на Wayback capture).

web_archive.info

Parameter Type Description
snap_counter integer Загальна кількість врахованих snapshot-ів Wayback.
years_counter integer Кількість років із активністю в архіві (сигнал віку домену).
first_ts integer Unix timestamp першого snapshot-а.
last_ts integer Unix timestamp найновішого snapshot-а.
years object Мапа year → monthly snapshot count (дані для sparkline/calendar).

web_archive.ts_summary

Parameter Type Description
average_karma_score integer Середній KarmaScore, 0..100 (мапиться на list field 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 Точки time series: timestamp, karma_score, lang, server_code, tags, detected_patterns.

web_archive.history[] (snapshot row)

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

web_archive.history[].content_info

Parameter Type Description
lang string | null Визначений код мови сторінки.
title, description, keywords string | null Meta/page text поля, що використовуються у фільтрах і 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 секунди).
  • Значення = масив lot objects, що завершуються в цей час (кілька платформ можуть мати один ключ).
Parameter Type Description
source string Джерело аукціонної платформи/реєстратора (напр. godaddy, namejet, dynadot, dropcatch, sedo, sav.com). Без урахування регістру у фільтрах.
sale_type string Тип listing-а (напр. auction, buynow, Closeout, Pre-Release, Dropped).
domain string Ім'я домену лоту.
item_id string Platform-specific lot/listing id.
end_time integer Час завершення лоту (Unix секунди); також використовується як grouping key у повному звіті.
price number Поточна ціна (зазвичай USD).
bids integer | null Кількість ставок, якщо застосовно.
currency string Символ/код валюти (за замовчуванням "$").
report_type string Власна база: auctions, backorder або buynow.
priority integer Внутрішня вага сортування/пріоритету (за замовчуванням 0).

Filter tip: auction_source у пошуку приймає просте джерело (godaddy) або складене значення source|sale_type (напр. godaddy|auction).

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

Параметр report_type

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

Пагінація і сортування (list endpoints)

Query parameters:

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

Depth limit: page × page_size ≤ 5000. Requests beyond this return 422 validation error.

Домени в URL

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

Типові workflow

1. Пошук → повний звіт

  1. POST https://api.karma.domains/v1/reports/search з filter body (див. OpenAPI → ReportListFilterSchema).
  2. Із report_list[] візьміть report_id і report_type.
  3. GET https://api.karma.domains/v1/reports/{report_type}/{report_id}.

Фільтри відповідають фільтрам у web UI — зручно звіряти з UI; для field schema дивіться OpenAPI.

2. Точний домен без довгого пошуку

  1. GET /v1/reports/by-domain/example.com
  2. У response matches[] — до одного запису на кожну базу, де домен існує.
  3. Оберіть потрібний report_type → GET /v1/reports/{report_type}/{report_id}.

Якщо matches порожній — домену немає в базах Karma.

3. Обране

  • Лише список: GET /v1/reports/favorites
  • Той самий список через search: POST /v1/reports/search з "favorites": true у body
  • Додати: POST /v1/reports/favorites з {"report_id": "...", "report_type": "expired"}
  • Видалити: DELETE /v1/reports/favorites/expired/{report_id}

4. Drop check (expired report)

GET /v1/reports/check/expired/{report_id} — report id, а не доменне ім'я.

  • У разі успішного check-а оновлює report record на сервері
  • is_expired: true — домен імовірно доступний для реєстрації (це не “WHOIS expiry date passed”)
  • Повторний live check для того самого report — не частіше одного разу на 3 години (business rule)
  • HTTP response cache-ується 1 годину для повторних GET з тим самим report_id (див. “Caching”)

5. Перевірка домену без report у базі

GET /v1/domains/checker/expiry/{domain} — live WHOIS/DNS; не змінює report у базі.

  • available: true — імовірно реєструється
  • available: false — зайнятий або зарезервований
  • Повторний запит для того самого домену в межах ~1 години може повернути cache response

6. Karma Metric on the fly

GET /v1/domains/checker/karma_metric/{domain} — Karma Metric із WayBack Machine; report не оновлює. Response fields — OpenAPI (KarmaMetricData). Response cache на домен — ~1 година.

Детальніше про Karma Metric у блозі

7. Баланс і план

GET /v1/user — email, balance (кредити), plan flags, subscription data. API key у response не повертається. Response cache ~1 хвилина на ключ — не poll-те частіше, ніж потрібно для актуального балансу.

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 у favorites миттєво змінюють server data, але повторні GET /favorites або POST /search з favorites: true можуть повертати застарілий список до закінчення cache (5 хв).

Приклади request (curl)

Замініть YOUR_API_KEY на ключ із профілю. Base 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"]
  }'

Filter body — будь-які поля з ReportListFilterSchema у OpenAPI.

Повний звіт

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

Lookup за доменом

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"

Інтеграційні use cases

Нічний pipeline відбору expired

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

Моніторинг списку імен перед реєстрацією

Черга доменів → GET /domains/checker/expiry/{domain} → розгалуження за available. Не потребує наявності report у Karma.Domains.

Синхронізація обраного з внутрішньою CRM

Періодичний GET /favorites; за дією користувача в CRM — POST/DELETE favorites. Враховуйте cache списку ~5 хв.

BI / funnel analytics

Експортуйте search pages, агрегуйте total_count і метрики з report_list без відкриття UI. Схема рядка списку — ReportListResponseSchema у OpenAPI.

MCP + scripts на одному ключі

Команда використовує MCP у Cursor для ad-hoc search і Public API для стабільного ETL. Загальний ліміт — 60 запитів за хвилину; плануйте batch-і та backoff на 429.

MCP і Public API

Public API (REST) MCP
Audience Розробники, scripts, ETL AI-асистенти (Cursor, Claude)
Interface HTTP + JSON Діалог, інструменти
Docs Ця сторінка + OpenAPI /uk/expired-domains-mcp/
Data Ті самі звіти й бази Те саме
Key & limit Спільні Спільні

Для нових code-інтеграцій починайте з REST. Для chat-експериментів — MCP.

FAQ

Де повний довідник полів фільтрів?

OpenAPI, schema ReportListFilterSchema. Значення полів збігаються з filter help в UI.

У чому різниця між available та is_expired?

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

Чому 403 за правильного ключа?

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

Чому API response не збігається з UI або щойно виконаною дією?

Через HTTP cache Public API — див. таблицю в “Caching”. Враховуйте TTL при синхронізації з UI.

Які значення sort_by дозволені?

Enum list у OpenAPI — назви колонок таблиці звітів у web app.

Чи потрібна ця сторінка, якщо є OpenAPI?

OpenAPI — source of truth для типів і полів. Ця сторінка додає контекст: ліміти, cache, порядок викликів, use cases і pitfalls, яких немає в schema.

Can I export the entire database via the API?

No. A single search is limited to 5000 rows of pagination depth, and your account can retrieve at most 50,000 list rows per day (UTC) across API, MCP, and UI. Use filters to narrow results; fetch full reports one domain at a time via GET /reports/{report_type}/{report_id}.

Чи є sandbox?

Окремого sandbox немає; використовуйте Pro-акаунт і дотримуйтеся rate limits. Для debug добре підходять GET /user і вузький POST /search зі strict filter.

Коди помилок

Code Meaning
200 Success
401 Unauthorized (key)
403 No Pro
404 Report або resource не знайдено
422 Помилка валідації body/query (invalid filter, sort_by, ...)
429 Перевищено rate limit
503 Rate limiter тимчасово недоступний

Error body зазвичай містить detail (string або масив validation objects). Приклад:

{
  "detail": "Invalid API key"
}

Корисні посилання

Спробуйте безкоштовно!

Використовуйте бонусні кредити!

Відкрити список доменів
+5