API ガイド

East Agile Tracker API は、人間と同じくらいエージェントのために設計されています。UI でできることはすべて API でできます — そして UI が公開していないいくつかのこともそこにあります。

このガイドは、10 分足らずでゼロから「バックログをスクリプトで操作する」状態へとあなたを導きます。完全なエンドポイントリファレンスについては API 仕様 を参照してください。

2 種類のキー

X-TrackerToken ヘッダーの API キー で認証します。2 種類あります。

• ユーザーキー（ea_user_…） — あなた として動作します。Account Settings → API Keys で作成します。個人用スクリプト、CLI ツール、統合に使います。
• エージェントキー（ea_agent_…） — 1 つのプロジェクト内の名前を持つエージェント として動作します。プロジェクトのオーナーとして Project Settings → Agents で作成します。AI エージェント — Claude Code、Codex、あなた自身のもの — が名前を持つチームメイトとしてプロジェクトに参加すべき場合に使います。

違い:

	ユーザーキー	エージェントキー
スコープ	あなたのすべてのプロジェクト	1 つの特定のプロジェクト
監査ログでのアイデンティティ	あなたの名前	エージェントの名前
ロール	各プロジェクトでのあなたのロール	キー作成時に設定（viewer または member）
取り消し	キーを取り消しても、他のキー/セッションでアクセスを維持	キーを取り消すと、エージェントは即座にアクセスを失う
最適な用途	個人の自動化、スクリプト	履歴であなたと区別できるべき AI エージェント

そのヘッダースタイルがお好みなら、Authorization: Bearer … も機能します。

Hello, API

あなたのプロジェクトを取得:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

または、エージェントキーで、それがスコープされたプロジェクトを一覧表示:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API は JSON、REST 風で、/api/v1/ でバージョン管理されています。人間とエージェントで同じ形です。

プロジェクトを作成する

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

レスポンスには project_id と、サーバーが適用したデフォルト（見積もりスケール、完了状態など）が含まれます。

ストーリーを作成する

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": 3,
    "labels": ["auth"]
  }'

ストーリーをライフサイクルに沿って動かす

遷移エンドポイントは要求された移動を検証し、エラー時には許可された次の状態を返します。

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

フィールドは to（to_state ではありません）です。移動が不正な場合 — 例えば unstarted から accepted へ直接スキップしようとした場合 — レスポンスは構造化されたエラー詳細付きの 422 invalid_transition です。

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] }
}

これは API をエージェントにやさしくする小さな点の 1 つです: エージェントは details.allowed を読み、散文をスクレイピングすることなく正しい次の手を選べます。

ストーリーにコメントする

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

コメントは、API キーを所有する者に帰属します — エージェントキーであれば、コメントの作者はエージェントです。

冪等な書き込み

すべての書き込みエンドポイントは Idempotency-Key ヘッダーを受け付けます。同じキーを同じボディで再試行すると、同じレスポンスが返ってきます。同じキーを 異なる ボディで再試行すると、409 idempotency_conflict が返ります。

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

これは再試行ループ内のエージェントにとって重要です — 書き込みの途中でクラッシュしても、同じキーで再試行すれば、重複したストーリーはできません。

一括遷移

多くのストーリーを一度に動かします。各ストーリーは独立して判断されます。1 つの不正な移動が他を失敗させることはありません。

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

イベントストリームを追跡する

人間が行うことに反応したいエージェントのために、events エンドポイントをポーリングします。

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

レスポンスは、行為者、リソース、変更を含む、カーソルでページ分割されたイベントのストリームです。各イベントには ID があります。最後に見た ID を since として渡せば、中断したところから再開できます。webhook なし、スクレイピングなし、見逃したイベントなし。

フィルター構文で検索する

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

利用可能なフィルター:

フィルター	例	説明
type:	type:feature	ストーリータイプでフィルター
state:	state:started	状態でフィルター
label:	label:"my label"	ラベルでフィルター
owner:	owner:claire	オーナーでフィルター
requester:	requester:tomas	リクエスターでフィルター
has:	has:blocker	ブロッカーを持つストーリー
is:	is:unestimated	見積もり前の feature

フリーテキストはタイトルと説明に一致します。フィルターをスペースで区切って組み合わせます — AND 結合されます。

API を発見する

ライブの OpenAPI 3 仕様は次にあります。

https://eastagiletracker.com/api/v1/openapi.json

Swagger UI は次にあります。

https://eastagiletracker.com/api/v1/docs

/openapi.json と /docs は認証不要です — エージェントはキーを持つ前に契約を読めます。キーを持てば、/api/v1/meta（これは 有効なキーを必要とします）が自身のアイデンティティとストーリータイプごとの遷移グラフを返します。参照データのルックアップ（/story_types、/story_states、/effort_scales）も認証不要です。これらを合わせることで、エージェントは試行錯誤の 403 なしに「ここで何ができるか？」に答えられます。

注意: 提供される openapi.json はパスを列挙していますが、現在は空のリクエストボディで出荷されています — 書き込みには 仕様 のフィールド形状を使ってください。

WebSocket コントロール

インタラクティブな自動化 — スクリプトからログイン済みのブラウザセッションを操作する、またはチュートリアルのために UI をリモート操作する — のために、WebSocket チャネルがあります。

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

ほとんどのユーザーはこれを必要としません。REST では不十分な場合のためにあります。

別のトラッカーからインポートする

一括移行をスクリプト化する場合:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

サポートされるソース: pivotal、jira、asana、gitlab、shortcut、trello、linear、plane、plane_json。

エラー形式

すべてのエラーは、最低限以下を持つ JSON です。

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

多くのエラーレスポンスには details オブジェクトも含まれます — validation_failed の details.fields（問題のあるフィールド名の 配列）、422 invalid_transition の details.allowed（from/to と並んで）。それらを使ってください。

ページネーション

リスト系エンドポイントは limit と cursor を受け付けます。カーソルは不透明です。前のレスポンスの next_cursor を渡してください。計算が安価な場合は、レスポンスヘッダーに総件数のための X-Tracker-Pagination-Total も含まれます。

次は何を

• API 仕様 — すべてのエンドポイント、すべての動詞、すべての形。
• 操作手順 → エージェント — UI 側: エージェントキーの発行、エージェントの命名、取り消し。
• はじめに — API の背後にある概念: ストーリー、状態、イテレーション、ベロシティ、エージェント。