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

MetodaCestaCo dělá
GET/balanceZůstatek kreditů
GET/sitesVaše weby, jejich ID a panely
POST/sitesPř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}/verifyHledat 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/personasKnihovna person
GET/runsVaš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/runsSpustit 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}/cancelZruš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}}

HTTPKódVýznam
400invalid_steps, invalid_concurrencyKroky nebo paralelita mimo rozsah; nic nebylo spuštěno a žádné kredity nebyly spotřebovány
400invalid_limit, invalid_cursorStránka seznamu běhů byla požádána s nesprávným limitem nebo před
400no_personasNebyla vybrána žádná persona nebo toto id na tomto webu není
400invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachableNový web s chybným polem; nic nebylo přidáno
400invalid_dry_run, invalid_idempotency_key, invalid_callback_urlChybný dry_run, Idempotency-Key nebo callback_url; nic nebylo spuštěno
400not_test_hostRežim testovací platby vyžaduje startovací stránku na testovacím hostiteli
401unauthorizedChybí nebo je neplatný klíč
402insufficient_creditsNedostatek kreditů
403domain_not_verifiedDoména není ověřena
404not_foundNa vašem účtu nic takového není
409too_many_runsPříliš mnoho běhů ve frontě
409site_exists, too_many_sitesDoména je již v vašem účtu, nebo má účet 20 webů
422not_verifiedDůkaz o doméně zatím nebyl nalezen
502generation_failedModel nedokázal vytvořit persony; zkuste to znovu nebo vyberte z knihovny
429rate_limitedPř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.