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}/verify | referral(招待ボーナスが支払われたか未払いか)の場合は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 | コード | 意味 |
|---|---|---|
| 400 | invalid_steps, invalid_concurrency | ステップ数または並列数が範囲外です。何も開始されず、クレジットも消費されませんでした |
| 400 | invalid_limit, invalid_cursor | ランリストのページが、誤った limit または before パラメータでリクエストされました |
| 400 | no_personas | ペルソナが選択されていないか、またはこのサイトに該当するIDがありません |
| 400 | invalid_url, invalid_task, unknown_persona, invalid_generate, invalid_report_lang, domain_unreachable | フィールドが誤っている新しいサイト;何も追加されませんでした |
| 400 | invalid_dry_run, invalid_idempotency_key, invalid_callback_url | 間違ったdry_run、Idempotency-Key、またはcallback_url;何も開始されませんでした |
| 400 | not_test_host | テスト決済モードでは、テストホスト上に開始ページが必要です |
| 401 | unauthorized | キーが見つからない、または無効です |
| 402 | insufficient_credits | クレジットが不足しています |
| 403 | domain_not_verified | ドメインが検証されていません |
| 404 | not_found | アカウントにそのようなデータはありません |
| 409 | too_many_runs | キュー内のテスト実行数が多すぎます |
| 409 | site_exists, too_many_sites | ドメインはすでにアカウントに登録されています、またはアカウントには20サイトまで登録可能です |
| 422 | not_verified | ドメインの証明はまだ見つかりません |
| 502 | generation_failed | モデルがペルソナを作成できませんでした。再試行するか、ライブラリから選択してください |
| 429 | rate_limited | リクエスト制限を超えました |
テスト実行がサイトに与える影響
検証済みドメインへのGETリクエストのみ送信されます。フォームは送信されず、パスワードやカード情報のフィールドは空のままなので、テスト実行は登録、ログイン、決済を行いません。例外はテストホスト用に有効にしたテスト決済モードです。注釈はAIモデルが生成するため、修正する前に必ず確認してください。