SCOPE
このドキュメントの公開範囲
このページは、外部サーバーや自動化ツールから利用することを想定した 33件の利用可能なAPIと、後方互換性のため残されている 3件の廃止済みルートを掲載しています。
アプリのログイン・メール認証を行う/auth/*、RevenueCat課金・Webhook、Pushトークン、
Discord OAuth・Bot Webhook、運営管理用/admin/*は、アプリ内部またはサービス運用専用であり公開APIの対象外です。
共通レスポンス形式
正常時はsuccess: trueとdataを返します。
{
"success": true,
"data": {
"id": "user_example_123",
"name": "Developer",
"credits": 24,
"isPremium": false
}
} エラー時はsuccess: falseとerror.code、error.messageを返します。場合によりerror.detailsも含まれます。
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing authentication credentials"
}
} QUICK START
最初のリクエスト
TestCrewアプリ内でAPIキーを発行し、X-API-Keyヘッダーへ設定します。
curl "https://api.test-crew.com/api/users/me" \
-H "X-API-Key: tc_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" AUTHENTICATION
認証とスコープ
APIキー認証
管理されたサーバーや自動化ツールからの呼び出しに使用します。
X-API-Key: tc_api_xxxxx JWT認証
TestCrewアプリのログインセッション、APIキー管理、JWT限定操作に使用します。
Authorization: Bearer YOUR_JWT | 表示 | 利用できる認証 |
|---|---|
公開 | 認証不要 |
公開 / Bearer JWT任意 | 認証不要。JWT使用時のみユーザー固有情報が付加される場合あり |
JWT / 任意のAPIキースコープ | JWT、full、read、app:createのいずれでも利用可能 |
JWT / read / full | JWT、read、full |
JWT / app:create / full | JWT、app:create、full |
JWT / full | JWTまたはfull |
JWT限定 | APIキーでは利用不可 |
公開WebサイトのJavaScript、公開GitHubリポジトリ、配布アプリへ直接埋め込まず、管理されたサーバー環境で使用してください。
API KEYS
APIキーの取得
- TestCrewアプリのプロフィール画面を開きます。
- 「API管理」を選択します。
- 「新しいAPIキーを作成」を選択します。
- 表示されたキーを安全な場所へ保存します。
現在のアプリ画面では名前のみを入力するため、fullスコープ・有効期限なしで発行されます。
権限や期限を限定する場合は、JWT認証でPOST /users/api-keysを使用してください。
キー本体は作成時に一度だけ表示されます。紛失した場合は新しいキーを作成し、古いキーを失効させてください。
| スコープ | 用途 |
|---|---|
full | APIキーで許可されているすべての外部連携操作 |
read | 読み取り、既読更新、テスト不能報告など |
app:create | アプリ掲載、テスト開始・完了、メッセージ、スレッド終了、お礼送信など |
curl -X POST "https://api.test-crew.com/api/users/api-keys" \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "My integration",
"scope": "read",
"expiresInSeconds": 2592000
}' ENDPOINTS
ユーザー・クレジット
プロフィール、アカウント、クレジット残高と取引履歴を扱います。
/users/me JWT / 任意のAPIキースコープ 認証済みユーザーのプロフィール、クレジット、プレミアム状態、Discord連携状態を取得します。
/users/me JWT / full プロフィール情報を更新します。
| 項目 | 型 | 説明 |
|---|---|---|
name | string | ユーザー名。1〜100文字。 |
avatar_url | string (URL) | アバター画像URL。 |
/users/me JWT限定 アカウントを削除し、個人情報と認証情報を匿名化します。
APIキーでは実行できず、403 JWT_REQUIREDが返ります。
/users/credits/balance JWT / 任意のAPIキースコープ 現在のクレジット残高を取得します。
/users/credits/transactions JWT / 任意のAPIキースコープ クレジット取引履歴を新しい順に最大50件取得します。
/users/credits/purchase JWT / 任意のAPIキースコープ 廃止済みです。RevenueCat購入後はアプリ内の課金同期フローを使用してください。
認証後、常に410 ENDPOINT_DEPRECATEDを返します。
/users/credits/verify-purchase JWT / 任意のAPIキースコープ 廃止済みです。RevenueCat購入後はアプリ内の課金同期フローを使用してください。
認証後、常に410 ENDPOINT_DEPRECATEDを返します。
/users/premium/verify JWT / 任意のAPIキースコープ 廃止済みです。プレミアム状態はアプリ内の課金同期フローを使用してください。
認証後、常に410 ENDPOINT_DEPRECATEDを返します。
ENDPOINTS
アプリ掲載
公開一覧、掲載作成、掲載状態、テスト情報を扱います。
/apps 公開 / Bearer JWT任意 公開中のAndroidアプリ一覧を取得します。
| 項目 | 型 | 説明 |
|---|---|---|
filter | all | new | premium | 表示フィルター。初期値はall。 |
page | integer | ページ番号。初期値は1。 |
limit | integer | 取得件数。初期値20、最大50。 |
seed | string | ランキング順を再現するための任意シード。未指定時は生成されます。 |
レスポンスにはpage、limit、total、totalPages、hasNextPage、hasPrevPage、seedが含まれます。
相互テストなどのユーザー固有情報はBearer JWT使用時のみ付加されます。X-API-Keyはこの公開一覧のオプショナル認証には使用されません。
/apps/home 公開 / Bearer JWT任意 ホーム画面向けに、実行可能な相互テスト候補を含むアプリ一覧を取得します。
| 項目 | 型 | 説明 |
|---|---|---|
filter | all | new | premium | 表示フィルター。初期値はall。 |
page | integer | ページ番号。初期値は1。 |
limit | integer | 取得件数。初期値20、最大50。 |
seed | string | ランキング順を再現するための任意シード。 |
ユーザー固有情報はBearer JWT使用時のみ付加されます。
/apps/:id 公開 指定したアプリ掲載の詳細を取得します。認証の有無でレスポンス内容は変わりません。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
/apps JWT / app:create / full 新しいAndroidアプリを掲載します。通常掲載は20クレジット、フィードバックテスター枠は1人につき4クレジットです。
| 項目 | 型 | 説明 |
|---|---|---|
appName 必須 | string | アプリ名。1〜100文字。 |
appIcon 必須 | string (URL) | アプリアイコンURL。 |
description 必須 | string | 説明。10〜1000文字。 |
platform 必須 | "android" | androidのみ。 |
playStoreUrl 必須 | Google Play URL | details?id=を含むGoogle Play詳細ページURL。 |
targetTesters 必須 | integer | 募集人数。3〜12。 |
feedbackTestersNeeded | integer | 追加フィードバック枠。0〜6、初期値0。 |
testingInstructions | string | テスト手順。最大2000文字。 |
curl -X POST "https://api.test-crew.com/api/apps" \
-H "X-API-Key: tc_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"appName": "My Android App",
"appIcon": "https://example.com/app-icon.png",
"description": "This is an Android app for testing.",
"platform": "android",
"playStoreUrl": "https://play.google.com/store/apps/details?id=com.example.app",
"targetTesters": 12,
"feedbackTestersNeeded": 2,
"testingInstructions": "Please test the login and main navigation."
}' /apps/my/listings JWT / read / full 自分が掲載しているアプリ一覧を取得します。
/apps/my/slots JWT / read / full 通常掲載枠、プレミアム掲載枠、使用状況などの枠情報を取得します。
/apps/:id JWT / full 自分のアプリ掲載を論理削除し、ステータスをexpiredへ変更します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
/apps/:id/pause JWT / full 自分のアプリ掲載を一時停止します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
/apps/:id/resume JWT / full 一時停止した自分のアプリ掲載を再開します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
/apps/:id/refresh JWT / full 自分のアプリ掲載を8クレジットでリフレッシュし、募集期間と表示順を更新します。activeまたはcompletedの掲載で利用できます。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
targetTesters | integer | 新しい募集人数。3〜12。省略時は現在値を維持します。 |
/apps/:id/testing-info JWT / app:create / full Google Play URLとテスト手順を更新し、必要に応じて問題報告の解決や再確認を要求します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
playStoreUrl 必須 | Google Play URL | details?id=を含むGoogle Play詳細ページURL。 |
testingInstructions | string | テスト手順。最大2000文字。 |
resolveIssueReports | boolean | 未解決のテスト不能報告を明示的に解決するか。 |
requestReview | boolean | needs_fix状態の掲載を公開前の再確認へ再提出するか。他の状態ではtrueを指定しても再確認は開始されません。 |
/apps/:id/setup-discord JWT / app:create / full 指定したアプリ掲載用のDiscordスレッドを作成または設定します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | アプリ掲載ID。 |
ENDPOINTS
テスト
テスト開始、完了、再開、不能報告、履歴と詳細を扱います。
/tests/start JWT / app:create / full 指定したアプリのテストを開始します。
| 項目 | 型 | 説明 |
|---|---|---|
appListingId 必須 | UUID | テストするアプリ掲載ID。 |
isFeedbackTest | boolean | フィードバックテストとして参加するか。初期値false。 |
/tests/:id/complete JWT / app:create / full 自分のテストを完了し、フィードバックを送信します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | テスト記録ID。 |
feedback 必須 | string | フィードバック。10〜2000文字。 |
rating | integer | 評価。1〜5。 |
screenshots | URL[] | スクリーンショットURL。最大5件。 |
条件を満たした場合にクレジットが付与されます。
/tests/:id/report-issue JWT / read / full 開始済みテストを実行できない理由を報告し、募集枠を解放します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | テスト記録ID。 |
reason 必須 | enum | store_url_unavailable、app_not_found、cannot_join_test、cannot_install、other。 |
diagnosticCode | enum | reasonとの対応は、store_url_unavailable: missing_or_invalid_url | open_url_failed、app_not_found: app_not_found、cannot_join_test: cannot_join_test、cannot_install: cannot_install、other: manual_other。 |
details | string | 補足。最大500文字。reasonがotherの場合は10文字以上必須。 |
/tests/my-tests JWT / read / full 自分のテスト履歴と進行状況を取得します。
/tests/:id JWT / read / full テスト記録の詳細を取得します。閲覧できるのはテスター本人または掲載者です。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | テスト記録ID。 |
/tests/:id/resume JWT / read / full 進行中のテストを再開するためのアプリ情報と状態を取得します。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | テスト記録ID。 |
ENDPOINTS
公開フィードバックスレッド
フィードバックの会話、既読、終了、お礼クレジット、通報を扱います。
/apps/:appId/feedback-threads JWT / read / full アプリごとの公開フィードバックスレッド一覧を取得します。
| 項目 | 型 | 説明 |
|---|---|---|
appId 必須 | UUID (path) | アプリ掲載ID。 |
page | integer | ページ番号。初期値1。 |
limit | integer | 取得件数。初期値20、最大50。 |
/feedback-threads/:testId JWT / read / full 指定したテストのフィードバックスレッド詳細を取得します。
| 項目 | 型 | 説明 |
|---|---|---|
testId 必須 | UUID (path) | テスト記録ID。 |
/feedback-threads/:testId/messages JWT / app:create / full フィードバックスレッドへメッセージを投稿します。
| 項目 | 型 | 説明 |
|---|---|---|
testId 必須 | UUID (path) | テスト記録ID。 |
body 必須 | string | 本文。1〜1000文字。 |
clientRequestId 必須 | string | クライアント側のリクエスト識別子。1〜200文字。 |
/feedback-threads/:testId/read JWT / read / full フィードバックスレッドを既読にします。
| 項目 | 型 | 説明 |
|---|---|---|
testId 必須 | UUID (path) | テスト記録ID。 |
/feedback-threads/:testId/close JWT / app:create / full フィードバックスレッドを終了します。
| 項目 | 型 | 説明 |
|---|---|---|
testId 必須 | UUID (path) | テスト記録ID。 |
/feedback-threads/:testId/rewards JWT / app:create / full フィードバックへのお礼としてクレジットを送ります。
| 項目 | 型 | 説明 |
|---|---|---|
testId 必須 | UUID (path) | テスト記録ID。 |
amount 必須 | 1 | 2 | 3 | 5 | 送るクレジット数。 |
idempotencyKey 必須 | string | 重複付与を防ぐ識別子。1〜200文字。 |
/feedback-content/reports JWT限定 初回フィードバックまたはメッセージを通報します。
| 項目 | 型 | 説明 |
|---|---|---|
testingRecordId 必須 | string | 対象のテスト記録ID。 |
targetType 必須 | initial_feedback | message | 通報対象の種類。 |
targetId 必須 | string | 通報対象ID。 |
reason 必須 | enum | personal_information、harassment、spam、unrelated、other。 |
details | string | 補足。最大500文字。 |
ENDPOINTS
APIキー管理
APIキーの一覧取得、作成、失効はJWT認証専用です。
/users/api-keys JWT限定 失効されていないAPIキー一覧を取得します。期限切れのキーが含まれる場合があります。キー本体は返らず、接頭辞、スコープ、期限、最終使用日時などが返ります。
/users/api-keys JWT限定 スコープと有効期限を指定して新しいAPIキーを作成します。キー本体はこのレスポンスで一度だけ返ります。
| 項目 | 型 | 説明 |
|---|---|---|
name 必須 | string | キー名。1〜50文字。 |
scope | full | read | app:create | スコープ。初期値full。 |
expiresInSeconds | positive integer | 有効期間(秒)。省略時は期限なし。 |
curl -X POST "https://api.test-crew.com/api/users/api-keys" \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "My integration",
"scope": "read",
"expiresInSeconds": 2592000
}' /users/api-keys/:id JWT限定 指定したAPIキーを失効させます。
| 項目 | 型 | 説明 |
|---|---|---|
id 必須 | UUID (path) | APIキーID。 |
ERRORS
エラーハンドリング
以下は外部連携で発生し得る代表的なコードです。各操作固有の失敗では、
GET_APPS_FAILEDやUPDATE_USER_FAILEDなど追加のコードが返る場合があります。
クライアントは未知のコードでもHTTPステータスとerror.messageを扱えるようにしてください。
| HTTP | コード | 説明 |
|---|---|---|
| 400 | VALIDATION_ERROR | 入力値が不正 |
| 400 | INSUFFICIENT_CREDITS | クレジット不足 |
| 400 | INVALID_STATUS | 現在の掲載状態では操作不可 |
| 400 | APP_NOT_ACTIVE | 掲載がテスト受付状態ではない |
| 400 | APP_FULL | 通常テスター枠が満了 |
| 400 | FEEDBACK_SLOTS_FULL | フィードバックテスター枠が満了 |
| 400 | CANNOT_TEST_OWN_APP | 自分のアプリはテスト不可 |
| 400 | UNSUPPORTED_PLATFORM | Android以外の掲載 |
| 401 | UNAUTHORIZED | 認証情報がない、無効、失効、期限切れ |
| 403 | FORBIDDEN | 操作権限がない |
| 403 | INSUFFICIENT_SCOPE | APIキースコープ不足 |
| 403 | JWT_REQUIRED | JWT認証が必要 |
| 403 | REVIEWER_NOT_ELIGIBLE | 公開前チェックの参加条件を満たしていない |
| 404 | NOT_FOUND | 対象リソースが存在しない |
| 409 | ALREADY_TESTING | すでに同じ掲載をテスト中または参加済み |
| 409 | TESTER_ACCOUNT_DELETED | テスターアカウントが削除済み |
| 409 | STALE_REVIEW_ROUND | 古い公開前確認ラウンド |
| 409 | TEST_REPORTED | 不能報告済みテストは完了不可 |
| 410 | ENDPOINT_DEPRECATED | 廃止済みエンドポイント |
| 500 | INTERNAL_ERROR | サーバー内部エラー |
廃止済みエンドポイント
POST /users/credits/purchasePOST /users/credits/verify-purchasePOST /users/premium/verify
これらは認証後、常に410 ENDPOINT_DEPRECATEDを返します。
RATE LIMITS
レート制限と再試行
固定の公開レート上限は保証されていません。短時間に大量のリクエストを送信しないでください。
429または5xxが返った場合、GETなどの冪等なリクエストは指数バックオフで再試行してください。
POST、PATCH、DELETEなど状態を変更するリクエストは、処理結果を確認してから再試行してください。
フィードバックのお礼送信にはidempotencyKeyがありますが、その他の変更系APIに共通の冪等性キー仕様はありません。
SUPPORT
APIに関するお問い合わせ
不具合報告や仕様に関する質問は、サポート窓口からご連絡ください。