REST API

Создайте ключ в разделе Настройки → API-ключи. Ключ в открытом виде показывается один раз и потом не восстанавливается; в читаемом виде хранится только его префикс. Передавайте его как bearer-токен в каждом запросе.

curl https://api.namescope.dev/v1/usage \
  -H "Authorization: Bearer ns_live_..."

У каждого ключа есть набор областей доступа. Запрос, которому нужна отсутствующая у ключа область, отклоняется с кодом 403 — поэтому ключ, выданный интеграции только для чтения, не сможет запустить платную проверку.

Любая проверка оплачивается кредитами — запущена она отсюда или из веб-приложения. Стоимость равна сумме запускаемых модулей: 100 кредитов при пяти модулях по умолчанию и меньше, если один отключить. Тариф начисляет кредиты каждый месяц, неизрасходованные переносятся.

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

• Недостаточный баланс → 429 с телом problem, где описана нехватка
• Тариф без доступа к API → 402 и ссылка на повышение тарифа
• Расходование кредитов отключено для рабочего пространства → 403

POST /v1/scans ставит проверку в очередь и сразу отвечает кодом 202. Проверка выполняется асинхронно: в ответе приходит scanId, а не результат.

curl -X POST https://api.namescope.dev/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tion studios",
    "regions": ["TR", "EM", "US"],
    "niceClasses": [9, 41],
    "tlds": ["com", "io"],
    "modules": ["trademark", "domain", "social"]
  }'

{ "scanId": "scn_...", "totalJobs": 12, "creditsSpent": 100, "balance": 1900 }

Опрашивайте GET /v1/scans/{id}, пока status не станет completed или completed_partial. Обычная проверка завершается меньше чем за минуту; опрашивайте примерно раз в секунду и увеличивайте интервал по мере ожидания, чтобы долгая проверка не съела лимит запросов.

curl https://api.namescope.dev/v1/scans/scn_... \
  -H "Authorization: Bearer ns_live_..."

Каждая запись в checks — это ответ одного источника по одной цели, со своим вердиктом, адресом sourceUrl, откуда он прочитан, и меткой времени fetchedAt. Объект summary появляется после завершения проверки и содержит оценку, уровень риска и сводку по товарным знакам.

Четыре справочных эндпоинта описывают, что может содержать запрос на проверку. Им нужна область доступа reference:read, и они бесплатны.

Ошибки возвращаются как problem-документы по RFC 9457 с типом содержимого application/problem+json. Поле type определяет вид сбоя, detail поясняет его, а некоторые ответы несут дополнительные поля, например upgradeUrl.

{
  "type": "https://namescope.dev/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough credits (balance 0, need 100). Top up or switch off a module to continue."
}

Лимиты считаются по каждому ключу в скользящем окне в одну минуту и передаются в каждом ответе, чтобы вы могли снизить нагрузку до того, как получите отказ.

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 41

Полное машиночитаемое описание доступно по адресу /v1/openapi.json. Аутентификация для него не нужна, поэтому клиент можно сгенерировать ещё до получения ключа.