REST APIを始める

Automation APIを使うと、開発ツールからフィードバックを読み、実装依頼を記録し、完成したGitHub PRを関連付けられます。MCPも同じAPIを使います。独自ツールやCIから直接利用できます。

基本URL

ホストされたAPIの基本URLはhttps://api.opentester.app/api/v1です。セルフホストの場合はHTTPSオリジンに/api/v1を付けます。次はローカルAPIの例です。

export OPENTESTER_API_URL="http://localhost:4000/api/v1"
export OPENTESTER_APP_ID="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"

OPENTESTER_APP_IDをコンソールのUUIDに置き換え、そのアプリのトークンを秘密の環境変数OPENTESTER_AGENT_TOKENとして渡します。docs.ドメインはAPIではありません。

事前準備

アプリ所有者としてアプリ情報とSDK → コーディングエージェント接続でトークンを発行します。一連の操作にはfeedback:read、work-items:read、work-items:writeが必要です。認証を参照してください。

最初のリクエスト

curl --fail-with-body --get \
  "$OPENTESTER_API_URL/apps/$OPENTESTER_APP_ID/automation/feedback" \
  --header "Authorization: Bearer $OPENTESTER_AGENT_TOKEN" \
  --header "Accept-Language: ja" \
  --data-urlencode "status=open" \
  --data-urlencode "limit=20"

フィードバックがない場合の正常な応答です。

{
  "feedback": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

エンドポイント

以下はすべて/api/v1/apps/:appId/automationからの相対パスです。

メソッド	パス	目的	エージェント権限
GET	/feedback	フィードバック一覧	feedback:read
GET	/feedback/:issueId	フィードバック詳細	feedback:read
POST	/change-requests	修正作業作成	work-items:write
GET	/change-requests	修正作業一覧	work-items:read
GET	/change-requests/:requestId	修正作業詳細	work-items:read
POST	/change-requests/:requestId/pull-request	GitHub PR関連付け	work-items:write
GET	/tokens	トークン一覧	Webセッションのみ
POST	/tokens	トークン発行	Webセッションのみ
DELETE	/tokens/:tokenId	トークン取り消し	Webセッションのみ

操作はURLのアプリに限定されます。所有者が同じでも、アプリごとに別のトークンを発行します。

リクエストとレスポンスの規則

• 本文はContent-Type: application/jsonのJSONで、上限は64 KiBです。
• IDはUUID文字列、日時はUTCのISO 8601文字列です。
• 未定義の本文フィールドやqueryは400になります。
• 成功時はGETが200、POSTが201、取り消しのDELETEが200です。作成の再試行も201です。
• 一覧はtotal、limit、offsetを含み、詳細はfeedbackまたはchangeRequestで包みます。
• 応答にはCache-Control: no-storeを設定します。

ページ分割

フィードバックと修正作業の一覧は同じパラメーターを使います。

パラメーター	既定値	範囲
limit	20	整数1–50
offset	0	整数0–100000

作成日時の降順で、同時刻ではID降順です。次ページにはoffset + limitを使います。取得中に新規データが追加される可能性があるため、複数ページを集めるときはIDで重複除去します。カーソル方式は未対応です。

言語とエラー

対応するエラーメッセージにはAccept-Language: en、ko、jaを使えます。選択された言語はContent-Languageで確認します。分岐には翻訳されるmessageではなくHTTPステータスを使います。エラーと再試行を参照してください。

連携の流れ

1. フィードバック取得でIDと再現手順を確認します。
2. 修正作業を作成し、目標、完了条件、関連報告を記録します。
3. 開発ツールで実装・テストし、GitHub PRを作成します。
4. 同じ作業にPR URLを関連付けます。

作業作成はエージェントを起動しません。PR関連付けはURLの記録であり、マージ、デプロイ、フィードバック状態の変更は行いません。アプリからの報告にはAndroid SDKを使います。