API
Základní adresa: https://senaste.ai/api/v1. Všechny cesty níže ji předpokládají. Pošlete hlavičku Authorization: Bearer uxp_.... Klíč vytvořte ve svém účtu. Limit je 60 požadavků za minutu; každá odpověď obsahuje X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (sekundy do další minuty) a stav 429 obsahuje Retry-After.
Celé API s tvarem každé odpovědi, jako OpenAPI 3.1 pro generátory kódu a Postman: https://senaste.ai/api/v1/openapi.json
Od nového webu ke zprávě
KEY=uxp_...
# 1. přidejte web; odpověď obsahuje jeho id a "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. umístěte důkaz na web (DNS TXT, soubor nebo meta tag), poté
curl -X POST https://senaste.ai/api/v1/sites/SITE_ID/verify -H "Authorization: Bearer $KEY"
# 3. odhadněte cenu bez spuštění, poté spusťte
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. sledujte ho nebo čekejte na callback
curl https://senaste.ai/api/v1/runs/RUN_ID -H "Authorization: Bearer $KEY"
Vynechte personas u běhu pro odeslání všech aktivních na panelu. Odpověď na 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":"..."}
Běží-li běh, GET /runs/{id} obsahuje 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"}]}Když běh skončí: callback_url
Při spuštění běhu s callback_url (https, veřejná adresa) je po jeho dokončení odeslán jeden POST na tuto adresu: done, failed, cancelled nebo interrupted. Tělo obsahuje {"event":"run.finished","run":{...}} se stavem, skóre a počty; výsledky získáte z GET /runs/{id}. Hlavičky: X-Senaste-Event, X-Senaste-Timestamp (sekundy Unix) a X-Senaste-Signature: sha256=…, což je HMAC-SHA256 od timestamp + "." + body s klíčem callback_secret, který se zobrazí pouze v odpovědi na POST /runs. Odpovězte kódem 2xx; jinak se to zopakuje po 10 a 60 sekundách. Přesměrování se nesledují.
// 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']));Metody
| Metoda | Cesta | Co dělá |
|---|---|---|
| GET | /balance | Zůstatek kreditů |
| GET | /sites | Vaše weby, jejich ID a panely |
| POST | /sites | Přidat web: url, task (až 500 znaků), personas (klíče knihovny z GET /personas) a/nebo generate (kolik model napíše z domovské stránky, až minutu), report_lang, audience. Odpověď obsahuje verification: DNS záznam, soubor a meta tag, kterýkoli z nich prokazuje doménu. |
| GET | /sites/{id} | Jeden web s panelem a, dokud není ověřen, verification |
| POST | /sites/{id}/verify | Hledat důkaz nyní. 200 s webem, když nalezen (a referral, pokud to připsalo nebo nepřipsalo bonus za pozvání), 422 not_verified, pokud ještě ne. |
| GET | /personas | Knihovna person |
| GET | /runs | Vaše běhy, nejnovější první, po stránkách: ?limit= 1 až 100 (výchozích 50). Když next není null, použijte ho v ?before= pro další stránku. |
| POST | /runs | Spustit test: steps 3 až 30, concurrency 1 až 4. Odpověď obsahuje warnings: forms, když úkol vyžaduje odeslání formuláře, nákup nebo registraci (test formuláře blokuje), offsite, když odkazuje na jinou doménu. "dry_run":true provede všechny kontroly a vrátí stav 200 s údaji credits, balance a would_start, aniž by něco spustilo. Záhlaví Idempotency-Key zajišťuje bezpečnost opakování: stejný klíč do 24 hodin vrátí již spuštěný běh (200, Idempotent-Replayed: true). callback_url je popsáno výše. |
| GET | /runs/{id} | Stav a výsledky pro každou personu. summary uvádí, kolik person prošlo webem a kolikrát selhal samotný test; takový výsledek má failure s fází, krokem a adresou.
Každý výsledek obsahuje steps (použitý prvek a effect, co prohlížeč udělal) a goal_check: části úkolu a zda jsou na snímcích obrazovky vidět. Persona, která tvrdí, že cíl splnila, ale její snímky ukazují jen část úkolu, má výsledek partly_reached. groups spojuje poznámky více person k jednomu problému; ID poznámky má formát persona:index. http uvádí HTTP chyby s typem zdroje, zda šlo o načtení stránky, konkrétní stránku a krok. Běh v čekací frontě má queue (pozice, běhy před vámi a jinými účty, sekundy do začátku a do připravenosti); běžící běh má progress; dokončený běh má waited_s a ran_s. Krok, který zadal hodnotu, má value, tedy to, co pole obsahovalo poté. notes_dropped uvádí poznámky, které kontrola vynechala, včetně důvodu. Chyba serveru v http také obsahuje at (UTC), url, retry (další požadavek o 2 s později), hindered a hlavičky odpovědi, podle kterých je správce webu najde ve svých záznamech. |
| POST | /runs/{id}/cancel | Zrušit, nedokončené kredity se vrátí |
Chyby
Formát: {"error":{"code":"...","message":"..."}}. Hodnota mimo rozsah také uvádí název pole a jeho limity: {"error":{"code":"invalid_steps","message":"...","field":"steps","min":3,"max":30,"got":40}}
| HTTP | Kód | Význam |
|---|---|---|
| 400 | invalid_steps, invalid_concurrency | Kroky nebo paralelita mimo rozsah; nic nebylo spuštěno a žádné kredity nebyly spotřebovány |
| 400 | invalid_limit, invalid_cursor | Stránka seznamu běhů byla požádána s nesprávným limitem nebo před |
| 400 | no_personas | Nebyla vybrána žádná persona nebo toto id na tomto webu není |
| 400 | invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachable | Nový web s chybným polem; nic nebylo přidáno |
| 400 | invalid_dry_run, invalid_idempotency_key, invalid_callback_url | Chybný dry_run, Idempotency-Key nebo callback_url; nic nebylo spuštěno |
| 400 | not_test_host | Režim testovací platby vyžaduje startovací stránku na testovacím hostiteli |
| 401 | unauthorized | Chybí nebo je neplatný klíč |
| 402 | insufficient_credits | Nedostatek kreditů |
| 403 | domain_not_verified | Doména není ověřena |
| 404 | not_found | Na vašem účtu nic takového není |
| 409 | too_many_runs | Příliš mnoho běhů ve frontě |
| 409 | site_exists, too_many_sites | Doména je již v vašem účtu, nebo má účet 20 webů |
| 422 | not_verified | Důkaz o doméně zatím nebyl nalezen |
| 502 | generation_failed | Model nedokázal vytvořit persony; zkuste to znovu nebo vyberte z knihovny |
| 429 | rate_limited | Překročen limit požadavků |
Co běh dělá s vaším webem
Pouze GET požadavky na ověřenou doménu. Formuláře se neodesílají a pole pro heslo a kartu zůstávají prázdná, takže běh se nikdy neregistruje, nepřihlašuje se ani neplatí. Výjimkou je režim testovací platby, který si zapnete pro testovací hostitele. Poznámky generuje model, zkontrolujte je před zásahem.