API ガイド

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

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

3 種類の認証情報

X-TrackerToken ヘッダーのキーで認証します。自分で発行するキーが 2 種類、そして MCP クライアントがあなたの代わりに取得する 3 つ目があります。

ユーザーキー（ea_user_…） — あなた として動作します。Account Settings → API Keys で作成します。個人用スクリプト、CLI ツール、統合に使います。
エージェントキー（ea_agent_…） — 1 つのプロジェクト内の名前を持つエージェント として動作します。Project Settings → Agents で作成します。AI エージェント — Claude Code、Codex、あなた自身のもの — が名前を持つチームメイトとしてプロジェクトに参加すべき場合に使います。
MCP トークン（ea_mcp_…） — 同意ページで承認した後に MCP クライアント（Claude、IDE）へ発行される OAuth 2.1 アクセストークン。あなたとして動作し、Account Settings → Connected apps で取り消せます。

アカウント設定で個人用 API キーを作成した直後に一度だけ表示されるダイアログ（このキャプチャではキーを伏せています）

設定手順の下にある Agent タブのキー作成フォーム。名前を入力し、ロールは member を選択

自分で発行する 2 種類の違い:

	ユーザーキー	エージェントキー
スコープ	あなたのすべてのプロジェクト	1 つの特定のプロジェクト
監査ログでのアイデンティティ	あなたの名前	エージェントの名前
ロール	各プロジェクトでのあなたのロール	キー作成時に設定（viewer、member、または manager — 発行したメンバー自身のロールを超えることはない）
取り消し	キーを取り消しても、他のキー/セッションでアクセスを維持	キーを取り消すかローテーションすると、エージェントは即座にアクセスを失う
最適な用途	個人の自動化、スクリプト	履歴であなたと区別できるべき 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"]
  }'

estimate はスケール値の ラベル を文字列で指定します — "3"、または Fibonacci スケールなら "13" — プロジェクトのスケール上のポイントと一致しなければならないからです。JSON の数値は拒否されます。

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

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

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 を読み、散文をスクレイピングすることなく正しい次の手を選べます。

遷移エンドポイントにとって rejected は終端です。reject されたストーリーを作業に戻すには POST …/stories/{sid}/restart を使います。POST …/stories/{sid}/reject は delivered なストーリーを reject する動詞形です。

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

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.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

検索

GET /projects/{id}/search?q=<query> は、プロジェクトのストーリーに対して強力な全文検索 + 構造化検索を実行します。クエリ言語は GitHub の issue 検索修飾子 をモデルにしているので、あなた（や AI エージェント）が GitHub で既に知っている構文がほぼそのまま通用します。

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

レスポンスは JSON のエンベロープで、ストーリーは関連度順に並びます。

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total はページサイズではなく、一致した全件数です。limit（デフォルト 50、最大 1000）と offset でページ分割し、sort=relevance（デフォルト）、created、created_asc、updated、または state で並べ替えます。

文法

フリーテキスト はストーリーのタイトル、参照、説明に一致します（全文検索、語幹処理とランク付けあり）。完全一致のフレーズは "引用符" で囲みます。
修飾子 は field:value です。選択肢はカンマで区切ります（フィールド内では OR）: type:bug,chore。修飾子同士はスペースで区切ります（修飾子間では AND）。
任意の語や修飾子の先頭に - を付けると否定になります: -label:wontfix。
日付とポイントの範囲: 両端を含む a..b、または片側開放の >x / <x。

修飾子

修飾子	例	一致するもの
`type:`	`type:bug,chore`	ストーリータイプ
`state:`	`state:started,finished`	ワークフロー状態
`label:`	`label:"my label"`	ラベル
`epic:`	`epic:"Checkout"`	エピック内のストーリー
`priority:`	`priority:p1`	優先度
`points:`	`points:3` · `points:1..5` · `points:>3`	見積もり値または範囲
`iteration:`	`iteration:42`	イテレーション id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	日付または範囲（日単位）。`release:` はストーリーのリリース日
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	名前またはメールで指定する人物 — メンバーとエージェント（`mention:` も含む）。`@me` はあなた自身
`has:blocker`	`has:blocker`	未解決のブロッカーがある
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	フラグ

mywork: は owner: のエイリアスです — mywork:me は owner:@me と同じです。古い scheduled: 修飾子は廃止され、黙って無視されます。release: を使ってください。

カンマによる OR（type:bug,chore）はファセット修飾子に適用されます。人物の修飾子（owner: requester: follower: reviewer: commenter: mention:）は単一の値のみを取ります。

例

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

同じクエリ文字列が、ボードの検索ボックス（ライブの結果列を開きます）とこの API の両方を動かします — 人間にもエージェントにも 1 つの文法です。コメント、タスク、ブロッカーの内容の検索はロードマップ上にあります。現在のフリーテキストはストーリー自身のタイトル、参照、説明を対象とします。

API を発見する

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

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

Swagger UI は次にあります。

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

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

提供される openapi.json には、書き込みエンドポイントのリクエストボディのスキーマが、各フィールドの maxLength も含めて載っているので、クライアントは送信前に検証できます。仕様は同じ形状を要約したものです。

WebSocket コントロール

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

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

token はブラウザセッションの JWT であり、API キーではありません — ea_user_* や ea_agent_* のキーはアップグレード前に拒否されます。ほとんどのユーザーはこれを必要としません。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、eat（East Agile Tracker 自身のエクスポート — ラウンドトリップ形式）。multipart エンドポイントは同期的に実行され、結果件数を返します。

GitHub はファイルではなく API からインポートします。JSON エンドポイント経由で、file は不要、リポジトリの座標だけを渡します。

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

JSON エンドポイントは非同期です。{ "import_id", "status" } とともに 202 を返すので、ジョブが done または failed に到達するまで GET /projects/{id}/imports/{import_id} をポーリングします。プロジェクトごとに同時に実行できるインポートは 1 つだけです — 実行中にもう一度呼び出すと 409 import_already_running になります。ジョブの進捗フィールドを含むループ全体は GitHub リポジトリからプロジェクトを作成するにあります。

token は通信上は任意ですが、取得そのものは常に認証されます — GitHub の GraphQL API 上で動作し、そこには匿名の階層が存在しないからです。token を省略するとサーバーはプラットフォームトークンで代替します。パブリックリポジトリのみ、すべての呼び出し元で共有され、その GraphQL 予算が 500 ポイントを下回ると import_github_shared_quota_low で拒否されます。プライベートリポジトリ、またはプラットフォームトークンを設定していないデプロイ（import_github_no_token）では、あなた自身のトークンが必要です。どのトークンが使われても、それはアップストリームの GitHub 呼び出しにのみ使われ、保存もエコーバックもされません。GitHub の未認証 REST 上限 60 リクエストを含む詳細は GitHub リポジトリからプロジェクトを作成するにあります。

ドライランプレビュー。 任意のソースに "dry_run": true（JSON）または -F "dry_run=true"（multipart）を追加します。インポートは実際の実行とまったく同じように解析・解決・重複排除を行い、同じ結果件数（imported、skipped、errors、unmatched）を生成してから、すべてをロールバックします — 何も書き込まれません。JSON エンドポイントでは、ドライランかどうかにかかわらず、件数はポーリングしたジョブ上に届きます。

制限。 アップロードボディは最大 10 MiB、単一のインポートは最大 5,000 ストーリー です。どちらかを超えると 400 になり、何も書き込まれません。ファイルの再インポートは安全です — すでにインポートされた行（ソース id で照合）は重複せずスキップされます。

プロジェクトをエクスポートする

フォーマットの一覧はどのプロジェクトロールでも取得できます。ダウンロードはオーナーのみです。

# 登録済みのエクスポートフォーマット: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# 1 つのフォーマットをダウンロード（eat はフル忠実度のラウンドトリップ CSV）
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

交換用フォーマット id: eat、jira、pivotal、shortcut、trello、asana、gitlab、linear、plane、plane_json、加えてドキュメント形式の pdf と docx。すべての添付ファイルは GET /projects/{id}/export/attachments から 1 つの zip としてダウンロードできます。

エラー形式

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

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

多くのエラーレスポンスには details オブジェクトも含まれます — validation_failed の details.fields（問題のあるフィールド名の配列）、422 invalid_transition の details.allowed（from/to と並んで）。それらを使ってください。429 rate_limited は、同じ JSON エンベロープに加えて Retry-After ヘッダーを伴います。

ページネーション

リスト系エンドポイントは limit と cursor を受け付けます。カーソルは不透明です。前のレスポンスの next_cursor を渡してください。limit の上限はエンドポイントごとに異なります — ストーリー、コメント、プロジェクトは 200、イベントは 500、検索と監査ログは 1000。レスポンスを切り詰めざるを得なかった通常の（カーソルなしの）リストは、ヘッダーでそれを伝えます: X-Tracker-Pagination-Truncated、-Limit、-Offset、-Next-Offset。最後のものを次のページの offset= として渡し返します。総件数のヘッダーはありません。

次は何を

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