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.namescope.dev/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.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 }

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.namescope.dev/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://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."
}

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

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.