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étodo | Ruta | Qué hace |
|---|---|---|
| GET | /balance | Saldo de créditos |
| GET | /sites | Tus sitios, sus ids y paneles |
| POST | /sites | Añ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}/verify | Busca 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 | /personas | La biblioteca de personas |
| GET | /runs | Tus 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 | /runs | Iniciar 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}/cancel | Cancelar, 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}}
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_steps, invalid_concurrency | Pasos o concurrencia fuera de rango; no se inició nada y no se gastó crédito |
| 400 | invalid_limit, invalid_cursor | Se pidió una página de la lista de pruebas con un limit o before incorrectos |
| 400 | no_personas | No se seleccionó ninguna persona, o un id no está en este sitio |
| 400 | invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachable | Un sitio nuevo con un campo incorrecto; no se añadió nada |
| 400 | invalid_dry_run, invalid_idempotency_key, invalid_callback_url | Un dry_run, Idempotency-Key o callback_url incorrectos; no se inició nada |
| 400 | not_test_host | El modo de pago de prueba necesita una página de inicio en un host de prueba |
| 401 | unauthorized | Clave faltante o inválida |
| 402 | insufficient_credits | Créditos insuficientes |
| 403 | domain_not_verified | Dominio no verificado |
| 404 | not_found | Nada de eso en tu cuenta |
| 409 | too_many_runs | Demasiadas pruebas en la cola |
| 409 | site_exists, too_many_sites | El dominio ya está en tu cuenta, o la cuenta tiene 20 sitios |
| 422 | not_verified | Aún no se encontró prueba del dominio |
| 502 | generation_failed | El modelo no pudo escribir personas; inténtalo de nuevo o elige de la biblioteca |
| 429 | rate_limited | Lí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.