API リファレンス

Human Tester REST APIの全エンドポイント仕様です。

ベースURL: https://human-tester.jp

認証

認証が必要なエンドポイントでは、Authorizationヘッダーに Bearer トークン形式でAPIキーまたはJWTトークンを指定します。

Authorization: Bearer ht_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

APIキーの形式: 本番用 ht_live_、テスト用 ht_test_ で始まる48文字の英数字。ダッシュボードの設定画面で発行・管理できます。

エンドポイント一覧

MethodPath説明認証
POST/api/auth/registerDeveloper登録-
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/keysAPIキーを作成必要
GET/api/keysAPIキー一覧必要
DELETE/api/keys/:idAPIキーを無効化必要

エンドポイント詳細

POST/api/auth/register

Developer登録

メール+パスワードでアカウントを作成。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"
}
POST/api/auth/login

ログイン

メール+パスワードでログイン。JWTトークンを発行します。

リクエストボディ

{
  "email": "user@example.com",
  "password": "securepassword123"
}

レスポンス (200)

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": "...",
  "email": "user@example.com",
  "name": "田中太郎"
}
GET/api/auth/me認証必要

自分のアカウント情報

認証済みユーザーの情報を取得します。

レスポンス (200)

{
  "id": "...",
  "email": "user@example.com",
  "name": "田中太郎",
  "role": "developer",
  "createdAt": "2026-02-10T10:00:00Z"
}
POST/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"
  }
}
GET/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"
    }
  ]
}
GET/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"
  }
}
GET/api/tests/:id/status認証必要

テスト進捗を取得

テストの現在の進行状況を取得します。テスターの完了数・割り当て状況が確認できます。

レスポンス (200)

{
  "testId": "...",
  "status": "in_progress",
  "targetTesters": 5,
  "completedTesters": 3,
  "updatedAt": "2026-02-10T11:30:00Z",
  "message": "3/5人のテスターがフィードバックを完了"
}
GET/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"
}
POST/api/tests/:id/cancel認証必要

テストをキャンセル

未完了(draft/recruiting/in_progress)のテストをキャンセルします。

リクエストボディ

{
  "reason": "方針変更のためキャンセル"
}

レスポンス (200)

{
  "testId": "...",
  "status": "cancelled",
  "cancelFee": 0
}
GET/api/test-types

テスト種別一覧

利用可能なテスト種別と料金を取得します。

レスポンス (200)

{
  "testTypes": [
    {
      "category": "ux_test",
      "label": "UXテスト",
      "description": "10分操作+評価+コメント",
      "basePrice": 500,
      "avgMinutes": 10
    },
    ...
  ]
}
GET/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
    },
    ...
  ]
}
POST/api/keys認証必要

APIキーを作成

新しいAPIキーを作成します。作成時のみ平文のキーが返されます。

リクエストボディ

{
  "name": "本番環境用"
}

レスポンス (201)

{
  "id": "...",
  "name": "本番環境用",
  "key": "ht_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "ht_live_xxxxxxxx",
  "createdAt": "2026-02-10T10:00:00Z"
}
GET/api/keys認証必要

APIキー一覧

作成済みのAPIキー一覧を取得します(平文のキーは含まれません)。

レスポンス (200)

{
  "keys": [
    {
      "id": "...",
      "name": "本番環境用",
      "prefix": "ht_live_xxxxxxxx",
      "status": "active",
      "lastUsedAt": "2026-02-10T10:00:00Z",
      "createdAt": "2026-02-01T10:00:00Z"
    }
  ]
}
DELETE/api/keys/:id認証必要

APIキーを無効化

指定したAPIキーを無効化(revoke)します。

レスポンス (200)

{
  "id": "...",
  "status": "revoked"
}

テスト作成パラメータ詳細

category(テスト種別)

説明料金/人
ux_testUI操作+5段階評価+コメント¥500
usability_testタスク完了率+つまずき発見¥700
survey選択肢+自由記述¥300
ab_test2バージョン比較+理由¥600
bug_hunt自由操作+バグ報告¥700

target_attributes(テスター属性条件)

フィールド選択肢
age_groupsstring[]teens, twenties, thirties, forties, fifties, sixties_plus
gendersstring[]male, female, other, undisclosed
occupationsstring[]employee, public_servant, self_employed, student, homemaker, freelance, other
industriesstring[]it, finance, medical, education, retail, manufacturing, service, other
it_proficiencystring[]beginner, general, intermediate, advanced
devicesstring[]smartphone, pc, tablet 等
browsersstring[]chrome, safari, firefox 等

status(テストステータス遷移)

draftrecruitingin_progresscompleted

draft / recruiting / in_progress からは cancelled にも遷移可能

エラーレスポンス

{
  "error": {
    "code": "TEST_NOT_FOUND",
    "message": "指定されたテストが見つかりません"
  }
}
HTTP Statuscode説明
400INVALID_INPUTリクエストパラメータが不正
401UNAUTHORIZEDAPIキーが無効または未指定
403FORBIDDEN権限なし(他のDeveloperのリソース等)
404TEST_NOT_FOUNDテストが見つからない
409INVALID_STATUS_TRANSITIONステータス遷移が不正
422INSUFFICIENT_TESTERS条件に合うテスターが不足
429RATE_LIMITEDレート制限超過(60リクエスト/分)
500INTERNAL_ERRORサーバー内部エラー