REST API

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

curl https://api.namesight.app/v1/usage \
  -H "Authorization: Bearer ns_live_..."

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

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

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

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

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

curl -X POST https://api.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lumina labs",
    "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.namesight.app/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://namesight.app/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

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

Безопасный повтор: передайте заголовок Idempotency-Key (любую уникальную строку) вместе с POST /v1/scans или rescan. Повтор с тем же ключом в течение 24 часов вернёт первый ответ — с Idempotent-Replayed: true — вместо запуска и оплаты второй проверки. Тот же ключ с другим телом отклоняется с 409.

curl -X POST https://api.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Idempotency-Key: 4f7c2c1e-order-1187" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lumina Labs","modules":["trademark","domain"]}'

Ожидание без опроса: GET /v1/scans/{id}?wait=60000 удерживает запрос, пока проверка не завершится или не истечёт ожидание (не более 60 секунд), и отвечает текущим состоянием. Один запрос, один слот лимита, без цикла.

Постраничный вывод: GET /v1/scans возвращает items и nextCursor. Передайте nextCursor как cursor для следующей страницы; null означает последнюю. status фильтрует по одному или нескольким статусам через запятую.

Вместо опроса зарегистрируйте https-адрес и получайте подписанный POST по завершении проверки. Адреса управляются в Настройки → API или через /v1/webhooks с областью webhooks:manage; рабочее пространство может держать десять. Секрет подписи показывается один раз — при создании и при смене.

Каждая доставка несёт четыре заголовка: x-namesight-event, x-namesight-delivery (один и тот же id при каждом повторе — для дедупликации), x-namesight-timestamp (секунды unix) и x-namesight-signature. Подпись — v1= и hex HMAC-SHA256 от "<timestamp>.<сырое тело>" под вашим секретом. Проверяйте по сырому телу запроса и отклоняйте метки старше пяти минут.

import { createHmac, timingSafeEqual } from "node:crypto";

// Express-style handler; keep the RAW body — a re-serialised JSON will not match.
app.post("/hooks/namesight", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.header("x-namesight-timestamp");
  const sig = req.header("x-namesight-signature");            // "v1=<hex>"
  const body = req.body.toString("utf8");
  const expected = "v1=" + createHmac("sha256", process.env.NAMESIGHT_WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || expected.length !== sig.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(401).end();
  }
  const event = JSON.parse(body);                              // { id, event, createdAt, test, data }
  res.status(202).end();                                       // ack first, work later
  if (!event.test) handleScanCompleted(event.data);            // data.scanId, data.status, data.score, data.url
});

Ответьте любым 2xx в течение десяти секунд, работу выполняйте потом. Всё остальное повторяется ещё четыре раза: через 30 секунд, 2, 10 и 60 минут. Десять доставок подряд, провалившие все попытки, выключают адрес; повторное включение сбрасывает счётчик. Кнопка теста шлёт синтетический scan.completed с test: true.

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