Human Tester REST APIの全エンドポイント仕様です。
ベースURL: https://human-tester.jp
認証が必要なエンドポイントでは、Authorizationヘッダーに Bearer トークン形式でAPIキーまたはJWTトークンを指定します。
Authorization: Bearer ht_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAPIキーの形式: 本番用 ht_live_、テスト用 ht_test_ で始まる48文字の英数字。ダッシュボードの設定画面で発行・管理できます。
| Method | Path | 説明 | 認証 |
|---|---|---|---|
| POST | /api/auth/register | Developer登録 | - |
| POST | /api/auth/login | ログイン | - |
| GET | /api/auth/me | 自分のアカウント情報 | 必要 |
| POST | /api/tests | テストを作成 | 必要 |
| GET | /api/tests | テスト一覧を取得 | 必要 |
| GET | /api/tests/:id | テスト詳細を取得 | 必要 |
| GET | /api/tests/:id/status | テスト進捗を取得 | 必要 |
| GET | /api/tests/:id/results | テスト結果を取得 | 必要 |
| POST | /api/tests/:id/cancel | テストをキャンセル | 必要 |
| GET | /api/test-types | テスト種別一覧 | - |
| GET | /api/usage | 利用状況を取得 | 必要 |
| POST | /api/keys | APIキーを作成 | 必要 |
| GET | /api/keys | APIキー一覧 | 必要 |
| DELETE | /api/keys/:id | APIキーを無効化 | 必要 |
/api/auth/registerメール+パスワードでアカウントを作成。Stripe CustomerとデフォルトのAPIキーも同時に作成されます。
リクエストボディ
{
"email": "user@example.com",
"name": "田中太郎",
"password": "securepassword123"
}レスポンス (201)
{
"userId": "...",
"email": "user@example.com",
"name": "田中太郎",
"role": "developer",
"apiKey": "ht_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token": "eyJhbGciOiJIUzI1NiIs...",
"createdAt": "2026-02-10T10:00:00Z"
}/api/auth/loginメール+パスワードでログイン。JWTトークンを発行します。
リクエストボディ
{
"email": "user@example.com",
"password": "securepassword123"
}レスポンス (200)
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"userId": "...",
"email": "user@example.com",
"name": "田中太郎"
}/api/auth/me認証必要認証済みユーザーの情報を取得します。
レスポンス (200)
{
"id": "...",
"email": "user@example.com",
"name": "田中太郎",
"role": "developer",
"createdAt": "2026-02-10T10:00:00Z"
}/api/tests認証必要新しいテストを作成し、テスターのマッチング・募集を開始します。カテゴリ・対象URL・テスター属性・テストシナリオを指定します。
リクエストボディ
{
"title": "LP改善のためのUXテスト",
"description": "新しいLPデザインの第一印象と使いやすさを評価してほしい",
"category": "ux_test",
"target_url": "https://example.com/lp-new",
"target_testers": 5,
"deadline": "2026-02-15T18:00:00Z",
"target_attributes": {
"age_groups": ["twenties", "thirties"],
"it_proficiency": ["general", "intermediate"]
},
"test_scenario": {
"tasks": [
{
"instruction": "トップページを見て第一印象を教えてください",
"evaluation_items": [
{ "label": "見やすさ", "type": "rating_5" },
{ "label": "わかりやすさ", "type": "rating_5" },
{ "label": "改善点", "type": "free_text" }
]
}
]
},
"options": {
"screen_recording": false
}
}レスポンス (201)
{
"test": {
"id": "...",
"title": "LP改善のためのUXテスト",
"status": "recruiting",
"category": "ux_test",
"estimatedCost": 2500,
"targetTesters": 5,
"createdAt": "2026-02-10T10:00:00Z"
}
}/api/tests認証必要作成したテストの一覧を取得します。
レスポンス (200)
{
"tests": [
{
"id": "...",
"title": "LP改善のためのUXテスト",
"category": "ux_test",
"status": "in_progress",
"targetTesters": 5,
"completedTesters": 3,
"estimatedCost": 2500,
"createdAt": "2026-02-10T10:00:00Z"
}
]
}/api/tests/:id認証必要特定のテストの詳細情報を取得します。
レスポンス (200)
{
"test": {
"id": "...",
"title": "LP改善のためのUXテスト",
"description": "...",
"category": "ux_test",
"status": "in_progress",
"targetUrl": "https://example.com/lp-new",
"targetTesters": 5,
"completedTesters": 3,
"estimatedCost": 2500,
"targetAttributes": { ... },
"testScenario": { ... },
"createdAt": "2026-02-10T10:00:00Z"
}
}/api/tests/:id/status認証必要テストの現在の進行状況を取得します。テスターの完了数・割り当て状況が確認できます。
レスポンス (200)
{
"testId": "...",
"status": "in_progress",
"targetTesters": 5,
"completedTesters": 3,
"updatedAt": "2026-02-10T11:30:00Z",
"message": "3/5人のテスターがフィードバックを完了"
}/api/tests/:id/results認証必要テストの結果を取得します。AI集計サマリー・定量スコア・定性コメントを含みます。include_raw=trueで個別回答の生データも取得可能。
レスポンス (200)
{
"testId": "...",
"status": "completed",
"category": "ux_test",
"targetTesters": 5,
"completedTesters": 5,
"summary": {
"overall_score": 72,
"key_findings": [
"CTAボタンの視認性が低い(5人中4人が指摘)",
"ファーストビューのコピーはわかりやすいと好評"
],
"recommendations": [
"CTAボタンの色をコントラストの高い色に変更",
"モバイル向けのフォントサイズを16px以上に"
],
"sentiment": "neutral"
},
"aggregated": {
"tasks": [
{
"task_index": 0,
"evaluations": {
"見やすさ": { "avg": 3.8 },
"わかりやすさ": { "avg": 4.0 }
}
}
]
},
"actualCost": 2500,
"completedAt": "2026-02-10T12:00:00Z"
}/api/tests/:id/cancel認証必要未完了(draft/recruiting/in_progress)のテストをキャンセルします。
リクエストボディ
{
"reason": "方針変更のためキャンセル"
}レスポンス (200)
{
"testId": "...",
"status": "cancelled",
"cancelFee": 0
}/api/test-types利用可能なテスト種別と料金を取得します。
レスポンス (200)
{
"testTypes": [
{
"category": "ux_test",
"label": "UXテスト",
"description": "10分操作+評価+コメント",
"basePrice": 500,
"avgMinutes": 10
},
...
]
}/api/usage認証必要指定期間の利用状況・課金情報を取得します。クエリパラメータ: ?period=today|week|month|all(デフォルト: month)
レスポンス (200)
{
"period": "month",
"totalTests": 12,
"completedTests": 8,
"totalResponses": 45,
"totalCost": 28500,
"breakdown": [
{
"category": "ux_test",
"count": 5,
"responses": 25,
"cost": 12500
},
...
]
}/api/keys認証必要新しいAPIキーを作成します。作成時のみ平文のキーが返されます。
リクエストボディ
{
"name": "本番環境用"
}レスポンス (201)
{
"id": "...",
"name": "本番環境用",
"key": "ht_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"prefix": "ht_live_xxxxxxxx",
"createdAt": "2026-02-10T10:00:00Z"
}/api/keys認証必要作成済みのAPIキー一覧を取得します(平文のキーは含まれません)。
レスポンス (200)
{
"keys": [
{
"id": "...",
"name": "本番環境用",
"prefix": "ht_live_xxxxxxxx",
"status": "active",
"lastUsedAt": "2026-02-10T10:00:00Z",
"createdAt": "2026-02-01T10:00:00Z"
}
]
}/api/keys/:id認証必要指定したAPIキーを無効化(revoke)します。
レスポンス (200)
{
"id": "...",
"status": "revoked"
}| 値 | 説明 | 料金/人 |
|---|---|---|
ux_test | UI操作+5段階評価+コメント | ¥500 |
usability_test | タスク完了率+つまずき発見 | ¥700 |
survey | 選択肢+自由記述 | ¥300 |
ab_test | 2バージョン比較+理由 | ¥600 |
bug_hunt | 自由操作+バグ報告 | ¥700 |
| フィールド | 型 | 選択肢 |
|---|---|---|
age_groups | string[] | teens, twenties, thirties, forties, fifties, sixties_plus |
genders | string[] | male, female, other, undisclosed |
occupations | string[] | employee, public_servant, self_employed, student, homemaker, freelance, other |
industries | string[] | it, finance, medical, education, retail, manufacturing, service, other |
it_proficiency | string[] | beginner, general, intermediate, advanced |
devices | string[] | smartphone, pc, tablet 等 |
browsers | string[] | chrome, safari, firefox 等 |
draft→recruiting→in_progress→completeddraft / recruiting / in_progress からは cancelled にも遷移可能
{
"error": {
"code": "TEST_NOT_FOUND",
"message": "指定されたテストが見つかりません"
}
}| HTTP Status | code | 説明 |
|---|---|---|
400 | INVALID_INPUT | リクエストパラメータが不正 |
401 | UNAUTHORIZED | APIキーが無効または未指定 |
403 | FORBIDDEN | 権限なし(他のDeveloperのリソース等) |
404 | TEST_NOT_FOUND | テストが見つからない |
409 | INVALID_STATUS_TRANSITION | ステータス遷移が不正 |
422 | INSUFFICIENT_TESTERS | 条件に合うテスターが不足 |
429 | RATE_LIMITED | レート制限超過(60リクエスト/分) |
500 | INTERNAL_ERROR | サーバー内部エラー |