API REST

Crea una clave en Ajustes → Claves de API. La clave en texto plano se muestra una sola vez y no puede recuperarse después; solo se guarda su prefijo en forma legible. Envíala como token bearer en cada petición.

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

Cada clave lleva un conjunto de ámbitos. Una petición que necesita un ámbito que la clave no tiene se rechaza con 403, de modo que una clave entregada a una integración de solo lectura no puede iniciar un análisis de pago.

Todos los análisis se pagan con créditos, los inicies aquí o en la aplicación web. Un análisis cuesta la suma de los módulos que ejecuta: 100 créditos con los cinco módulos por defecto y menos si dejas alguno fuera. Tu plan otorga créditos cada mes y los no usados se acumulan.

El cargo se registra antes de encolar cualquier trabajo, así que un análisis que no puede pagarse nunca se ejecuta ni deja ningún registro. Si el encolado falla después del cargo, los créditos se reembolsan automáticamente.

• Saldo insuficiente → 429 con un cuerpo de problema que explica el faltante
• Plan sin acceso a la API → 402 y una URL de mejora de plan
• Gasto de créditos desactivado en el espacio de trabajo → 403

POST /v1/scans encola un análisis y responde 202 de inmediato. El análisis es asíncrono: la respuesta lleva un scanId, no el resultado.

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 }

Consulta GET /v1/scans/{id} hasta que status sea completed o completed_partial. Un análisis típico termina en menos de un minuto; consulta aproximadamente una vez por segundo y amplía el intervalo mientras esperas, para que un análisis largo no consuma tu límite de peticiones.

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

Cada entrada de checks es una fuente respondiendo sobre un objetivo, con su propio veredicto, el sourceUrl del que se leyó y la marca de tiempo fetchedAt. El objeto summary aparece cuando el análisis termina y contiene la puntuación, la banda de riesgo y el recuento de marcas.

Cuatro endpoints de consulta describen lo que puede contener una petición de análisis. Necesitan el ámbito reference:read y no cuestan nada.

Los errores son documentos de problema RFC 9457 enviados como application/problem+json. El campo type identifica el fallo, detail lo explica y algunos llevan datos adicionales como 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."
}

Los límites de peticiones se cuentan por clave sobre un minuto deslizante y se informan en cada respuesta, de modo que puedas reducir el ritmo antes de que te rechacen.

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

Además de iniciar y leer un análisis, una clave puede repetirlo, reintentar las fuentes que no respondieron, borrarlo, compartir su informe, listar los proyectos del espacio y generar ideas de nombres. Cada acción exige el scope indicado.

Reintentar sin riesgo: envía una cabecera Idempotency-Key (cualquier cadena única) con POST /v1/scans o un rescan. Un reintento con la misma clave en 24 horas repite la primera respuesta — con Idempotent-Replayed: true — en vez de iniciar y cobrar un segundo análisis. La misma clave con otro cuerpo se rechaza con 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"]}'

Esperar sin sondear: GET /v1/scans/{id}?wait=60000 mantiene la petición hasta que el análisis termina o vence la espera (máximo 60 segundos), y responde con el análisis tal como está. Una petición, una ranura del límite, sin bucle.

Paginación: GET /v1/scans responde con items y nextCursor. Devuelve nextCursor como cursor para la página siguiente; null indica la última. status filtra por uno o más estados separados por comas.

En lugar de sondear, registra un endpoint https y recibe un POST firmado cuando termine un análisis. Los endpoints se gestionan en Ajustes → API o mediante /v1/webhooks con el scope webhooks:manage; un espacio puede tener diez. El secreto de firma se muestra una sola vez, al crearlo y al rotarlo.

Cada entrega lleva cuatro cabeceras: x-namesight-event, x-namesight-delivery (el mismo id en cada reintento, para deduplicar), x-namesight-timestamp (segundos unix) y x-namesight-signature. La firma es v1= seguido del HMAC-SHA256 en hexadecimal de "<timestamp>.<cuerpo crudo>" con tu secreto. Verifícala contra el cuerpo crudo de la petición y rechaza marcas de tiempo de más de cinco minutos.

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
});

Responde con cualquier 2xx en diez segundos y haz el trabajo después. Cualquier otra respuesta se reintenta cuatro veces más: a los 30 segundos, 2, 10 y 60 minutos. Diez entregas seguidas que fallan en todos sus intentos desactivan el endpoint; reactivarlo pone el contador a cero. El botón de prueba envía un scan.completed sintético con test: true.

La descripción completa legible por máquina se sirve en /v1/openapi.json. No requiere autenticación, así que puedes generar un cliente a partir de ella antes incluso de tener una clave.