API

Dirección base: https://senaste.ai/api/v1. Todas las rutas de abajo van tras ella. Envía el encabezado Authorization: Bearer uxp_.... Crea una clave en tu cuenta. El límite es de 60 solicitudes por minuto; cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta el siguiente minuto), y una respuesta 429 incluye Retry-After.

Toda la API con la forma de cada respuesta, como OpenAPI 3.1 para generadores de código y Postman: https://senaste.ai/api/v1/openapi.json

De un sitio nuevo a un informe

KEY=uxp_...
# 1. añade el sitio; la respuesta tiene su id y "verification"
curl -X POST https://senaste.ai/api/v1/sites -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/pricing","task":"Find the price of the Pro plan","personas":["impulse","price"],"generate":2}'
# 2. coloca una verificación en el sitio (DNS TXT, el archivo o la etiqueta meta) y luego
curl -X POST https://senaste.ai/api/v1/sites/SITE_ID/verify -H "Authorization: Bearer $KEY"
# 3. calcula el coste de la prueba sin iniciarla y luego iníciala
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"site":"SITE_ID","steps":20,"dry_run":true}'
curl -X POST https://senaste.ai/api/v1/runs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-1234" \
  -d '{"site":"SITE_ID","steps":20,"concurrency":3,"callback_url":"https://example.com/hooks/senaste"}'
# 4. sigue su avance o espera el callback
curl https://senaste.ai/api/v1/runs/RUN_ID -H "Authorization: Bearer $KEY"

Omite personas en una prueba para enviar a todas las habilitadas en el panel. Una respuesta a POST /runs:

{"id":"rmhb2x1k4f9a0c3d1","site":"s1a2b3c4d5e6","domain":"example.com","status":"queued","personas":8,"steps":20,
 "credits":8,"refunded":0,"charged":8,"created":"2026-11-09T10:00:00.000Z","started":null,"finished":null,
 "queue":{"position":1,"ahead_yours":0,"ahead_others":0,"start_in_s":0,"done_in_s":190},
 "callback":{"url":"https://example.com/hooks/senaste","status":null},"warnings":[],"callback_secret":"..."}

Mientras se ejecuta, GET /runs/{id} tiene progress:

"progress":{"phase":"walking","percent":41,"personas_done":3,"personas_total":8,"steps_done":71,"steps_total":160,"eta_s":190,
 "personas":[{"persona":"p01","name":"Impulse buyer","step":20,"state":"done","outcome":"gave_up"},
             {"persona":"p02","name":"Price-first evaluator","step":7,"state":"walking"}]}

Cuando termina una prueba: callback_url

Una prueba iniciada con callback_url (https, una dirección pública) envía un POST a esa dirección cuando termina: done, failed, cancelled o interrupted. El cuerpo es {"event":"run.finished","run":{...}} con el estado, la puntuación y los recuentos; los resultados se obtienen con GET /runs/{id}. Cabeceras: X-Senaste-Event, X-Senaste-Timestamp (segundos Unix) y X-Senaste-Signature: sha256=…, el HMAC-SHA256 de timestamp + "." + body con la clave callback_secret, que solo muestra la respuesta a POST /runs. Responde con 2xx; si no, se reintenta a los 10 y a los 60 segundos. No se siguen redirecciones.

// Node.js
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.headers['x-senaste-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-senaste-signature']));

Métodos

MétodoRutaQué hace
GET/balanceSaldo de créditos
GET/sitesTus sitios, sus ids y paneles
POST/sitesAñade un sitio: url, task (hasta 500 caracteres), personas (claves de la biblioteca desde GET /personas) y/o generate (cuántas escribe el modelo desde la página principal, hasta un minuto), report_lang, audience. La respuesta tiene verification: el registro DNS, el archivo y la metaetiqueta, cualquiera de los cuales demuestra el dominio.
GET/sites/{id}Un sitio con su panel y, hasta que se verifique, verification
POST/sites/{id}/verifyBusca la verificación ahora. 200 con el sitio cuando se encuentra (y referral cuando esto pagó o no un bono de invitación), 422 not_verified cuando aún no.
GET/personasLa biblioteca de personas
GET/runsTus pruebas, las más recientes primero, una página a la vez: ?limit= de 1 a 100 (50 por defecto). Cuando next no sea null, usa ?before= con ese valor para la siguiente página.
POST/runsIniciar una prueba: steps de 3 a 30, concurrency de 1 a 4. La respuesta tiene warnings: forms cuando una tarea pide enviar un formulario, comprar o iniciar sesión (la prueba retiene los formularios), offsite cuando nombra otro dominio. "dry_run":true ejecuta todas las comprobaciones y responde 200 con credits, balance y would_start, sin iniciar nada. La cabecera Idempotency-Key hace que un reintento sea seguro: la misma clave dentro de 24 horas devuelve la prueba que inició (200, Idempotent-Replayed: true). callback_url se describe arriba.
GET/runs/{id}Estado y resultados por persona. summary indica cuántas personas recorrieron el sitio y cuántas se detuvieron por un fallo de la propia prueba; ese resultado tiene failure con la etapa, el paso y la dirección. Cada resultado tiene steps (el elemento usado y effect, lo que hizo el navegador) y goal_check: las partes de la tarea y si las pantallas muestran cada una. Una persona que dice haber alcanzado la meta mientras sus pantallas muestran solo parte de la tarea tiene el resultado partly_reached. groups agrupa notas de varias personas sobre un mismo problema; un id de nota es persona:index. http enumera errores HTTP con el tipo de recurso, si fue una carga de página, la página y el paso. Una prueba en cola tiene queue (posición, pruebas por delante de la tuya y de otras cuentas, segundos hasta que empiece y hasta que esté lista); una en ejecución tiene progress; una finalizada tiene waited_s y ran_s. Un paso que ha escrito tiene value, lo que contenía el campo después. notes_dropped enumera las notas que la verificación omitió, con el motivo. Un error de servidor en http también tiene at (UTC), url, retry (otra solicitud 2 s después), hindered y los encabezados de respuesta con los que un propietario del sitio puede encontrarlo en sus registros.
POST/runs/{id}/cancelCancelar, los créditos no usados se devuelven

Errores

Formato: {"error":{"code":"...","message":"..."}}. Un valor fuera de rango también indica el campo y sus límites: {"error":{"code":"invalid_steps","message":"...","field":"steps","min":3,"max":30,"got":40}}

HTTPCódigoSignificado
400invalid_steps, invalid_concurrencyPasos o concurrencia fuera de rango; no se inició nada y no se gastó crédito
400invalid_limit, invalid_cursorSe pidió una página de la lista de pruebas con un limit o before incorrectos
400no_personasNo se seleccionó ninguna persona, o un id no está en este sitio
400invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachableUn sitio nuevo con un campo incorrecto; no se añadió nada
400invalid_dry_run, invalid_idempotency_key, invalid_callback_urlUn dry_run, Idempotency-Key o callback_url incorrectos; no se inició nada
400not_test_hostEl modo de pago de prueba necesita una página de inicio en un host de prueba
401unauthorizedClave faltante o inválida
402insufficient_creditsCréditos insuficientes
403domain_not_verifiedDominio no verificado
404not_foundNada de eso en tu cuenta
409too_many_runsDemasiadas pruebas en la cola
409site_exists, too_many_sitesEl dominio ya está en tu cuenta, o la cuenta tiene 20 sitios
422not_verifiedAún no se encontró prueba del dominio
502generation_failedEl modelo no pudo escribir personas; inténtalo de nuevo o elige de la biblioteca
429rate_limitedLímite de solicitudes excedido

Qué hace una prueba en tu sitio

Solo solicitudes GET al dominio verificado. Los formularios no se envían y los campos de contraseña y tarjeta permanecen vacíos, por lo que una prueba nunca se registra, inicia sesión o paga. La excepción es el modo de pago de prueba, que activas para un host de prueba. Las notas las escribe un modelo, revísalas antes de actuar.