API

基本アドレス: https://senaste.ai/api/v1. 以下のすべてのパスはそれに従います。ヘッダーを送信してください Authorization: Bearer uxp_.... アカウントにAPIキーを作成してください。制限は1分あたり60リクエストです。すべてのレスポンスにはX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset(次の分までの秒数)が含まれ、429ステータスにはRetry-Afterが含まれます。

コードジェネレーターやPostman用のOpenAPI 3.1形式のAPI全体と、各レスポンスの形状: https://senaste.ai/api/v1/openapi.json

新しいサイトからレポートまで

KEY=uxp_...
# 1. サイトを追加する。返信にはそのサイトのIDと「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. サイトに証明を1つ設置します(DNS TXT、ファイル、またはメタタグ)、その後
curl -X POST https://senaste.ai/api/v1/sites/SITE_ID/verify -H "Authorization: Bearer $KEY"
# 3. 実行前にコストを計算し、その後で実行する
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. それを追跡するか、コールバックを待つ
curl https://senaste.ai/api/v1/runs/RUN_ID -H "Authorization: Bearer $KEY"

personasを指定しない場合、パネル上の有効なすべてのAIが実行されます。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":"..."}

実行中に、GET /runs/{id} は 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"}]}

ラン終了時のコールバックURL

callback_url(https、公開アドレス)を指定して開始されたrunは、完了時に1回のPOSTを送信します(完了、失敗、キャンセル、中断)。本文は{"event":"run.finished","run":{...}}で、ステータス、スコア、カウントが含まれます。結果はGET /runs/{id}から取得します。ヘッダー:X-Senaste-Event、X-Senaste-Timestamp(Unix秒)、X-Senaste-Signature: sha256=…(timestamp + "." + bodyのHMAC-SHA256、キーはcallback_secret。このキーはPOST /runsへのレスポンスでのみ表示されます)。2xxで応答してください。それ以外の場合、10秒と60秒後に再試行されます。リダイレクトはフォローされません。

// 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']));

メソッド

メソッドパス機能
GET/balanceクレジット残高
GET/sitesあなたのサイト、そのID、およびパネル
POST/sitesサイトを追加:url、task(最大500文字)、personas(GET /personasからのライブラリキー)および/またはgenerate(モデルがホームページから生成する数、最大1分)、report_lang、audience。レスポンスにはverificationが含まれます:DNSレコード、ファイル、metaタグのいずれかがドメインの証明になります。
GET/sites/{id}1つのサイト、そのパネル、および検証されるまでverification
POST/sites/{id}/verifyreferral(招待ボーナスが支払われたか未払いか)の場合は422 not_verified(未検証)のときを除き、サイトでの検証を確認してください。
GET/personasペルソナライブラリ
GET/runsあなたのテスト実行履歴(最新順、ページネーション対応):?limit= は 1〜100(デフォルトは 50)。next が null でない場合は、次のページを取得するために ?before= にその値を指定してください。
POST/runs実行を開始:steps は3〜30、concurrency は1〜4。レスポンスにはwarningsが含まれます:formsは、タスクでフォーム送信、購入、またはサインアップを要求する場合(テストはフォーム送信を一時停止)、offsiteは別のドメインを参照する場合。 "dry_run":true はすべてのチェックを実行し、何も開始せずに credits、balance、would_start を含む 200 を返します。Idempotency-Key ヘッダーは再試行を安全にします:24時間以内に同じキーを使用すると、開始されたランが返されます(200、Idempotent-Replayed: true)。callback_url は上記で説明されています。
GET/runs/{id}各personaの状態と結果。summaryは、サイトを巡回したpersonaの数とテスト自体が失敗した数を示します。この種の結果は、failureとしてステージ、ステップ、アドレスを伴って記録されます。 各結果にはsteps(使用した要素とeffect、ブラウザの動作)とgoal_check(タスクの各部分と、それらがスクリーンショットに映っているか)が含まれます。ゴールに到達したと報告しているが、スクリーンショットではタスクの一部しか映っていない場合、結果はpartly_reachedとなります。groupsは1つの問題に関する複数のpersonaのメモを結合します。メモのIDはpersona:indexの形式です。httpには、リソースタイプ、ページ読み込みかどうか、ページ、ステップを含むHTTPエラーがリストされます。キュー待ちのrunにはqueue(順位、あなたや他のアカウントのrunの残り数、開始までの秒数、準備完了までの秒数)が含まれます。実行中のrunにはprogressが、完了したrunにはwaited_sとran_sが含まれます。 入力ステップにはvalue(入力後のフィールドの値)が含まれます。notes_droppedには、チェックが除外したノートとその理由がリストされます。httpのサーバーエラーには、at(UTC)、url、retry(2秒後に1回再試行)、hindered、およびサイト所有者がログで確認できるレスポンスヘッダーも含まれます。
POST/runs/{id}/cancelキャンセル。未完了のクレジットは返金されます

エラー

形式: {"error":{"code":"...","message":"..."}}. 範囲外の値もフィールドとその制限を示します: {"error":{"code":"invalid_steps","message":"...","field":"steps","min":3,"max":30,"got":40}}

HTTPコード意味
400invalid_steps, invalid_concurrencyステップ数または並列数が範囲外です。何も開始されず、クレジットも消費されませんでした
400invalid_limit, invalid_cursorランリストのページが、誤った limit または before パラメータでリクエストされました
400no_personasペルソナが選択されていないか、またはこのサイトに該当するIDがありません
400invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachableフィールドが誤っている新しいサイト;何も追加されませんでした
400invalid_dry_run, invalid_idempotency_key, invalid_callback_url間違ったdry_run、Idempotency-Key、またはcallback_url;何も開始されませんでした
400not_test_hostテスト決済モードでは、テストホスト上に開始ページが必要です
401unauthorizedキーが見つからない、または無効です
402insufficient_creditsクレジットが不足しています
403domain_not_verifiedドメインが検証されていません
404not_foundアカウントにそのようなデータはありません
409too_many_runsキュー内のテスト実行数が多すぎます
409site_exists, too_many_sitesドメインはすでにアカウントに登録されています、またはアカウントには20サイトまで登録可能です
422not_verifiedドメインの証明はまだ見つかりません
502generation_failedモデルがペルソナを作成できませんでした。再試行するか、ライブラリから選択してください
429rate_limitedリクエスト制限を超えました

テスト実行がサイトに与える影響

検証済みドメインへのGETリクエストのみ送信されます。フォームは送信されず、パスワードやカード情報のフィールドは空のままなので、テスト実行は登録、ログイン、決済を行いません。例外はテストホスト用に有効にしたテスト決済モードです。注釈はAIモデルが生成するため、修正する前に必ず確認してください。