East Agile Tracker API の REST エンドポイント完全リファレンス。認証とロール、プロジェクト、ストーリー、エピック、イテレーション、イベント、インポートとエクスポート。
完全な REST エンドポイントリファレンスです。チュートリアルと例については API ガイド を参照してください。
プロジェクトの member が Web UI でできることはすべてここで利用できます — SPA はこの同じ API を消費しています。manager ロールを必要とする操作は (manager) とマークされています。それ以外はプロジェクトメンバーシップのみ（または、(viewer) とマークされた読み取りについては任意のアクセスレベル）を必要とします。以下の表はサーバーがマウントするすべてのルートグループを挙げています。1 行で要約されているものは、ライブの openapi.json に完全に記述されています。
https://api.eastagiletracker.com/api/v1API には専用のホストがあります: eastagiletracker.com は Web アプリを提供し、/api/v1/… には 404 を返します。すべてのリクエストとレスポンスは JSON です。ただし、multipart を受け付けるいくつかのファイルアップロードエンドポイントを除きます。
2 つのグループは 1 階層上、/api/v1 ではなく /api の下にあります: 認証サーフェス（/api/auth/*）と公開お問い合わせフォーム（/api/contact）です。これらを /api/v1/… と書いた場合は 404 が返ります。
すべての認証済みリクエストは、次のいずれかで認証情報を送ります。
X-TrackerToken: <key>Authorization: Bearer <key>
ユーザーキーは ea_user_、エージェントキーは ea_agent_、MCP アクセストークンは ea_mcp_ で始まります。API ガイド → 3 種類の認証情報 を参照してください。
認証不要のエンドポイント: /openapi.json、/docs、/api/auth/* エンドポイント、参照データのルックアップ（/story_types、/story_states、/effort_scales、/priority_scales）。/meta は 認証済み です — 任意の有効なキーが機能しますが、プロジェクトスコープではありません（プロジェクトにバインドされたエージェントキーでも到達できます）。
4 つのレベルがプロジェクトスコープのエンドポイントを制御します。
| レベル | 通過する者 | 典型的な操作 |
|---|---|---|
| public viewer | 公開設定のプロジェクトであれば誰でも | ボードの読み取り: ストーリー、イテレーション、検索、ストーリーと Epic のアクティビティ（アクターの詳細はマスクされる） |
| viewer | viewer, member, manager | 読み取り（ストーリーの一覧/取得、検索、メトリクス、エクスポートフォーマットの一覧） |
| member | member, manager | すべての作業項目の書き込み（ストーリー、タスク、コメント、…）、イベントストリーム |
| manager | manager のみ | プロジェクト設定、メンバーシップ管理、エージェントキー、削除、インポート、エクスポートのダウンロード、バックアップ、監査ログ |
エージェントはメンバーと同じロール — viewer、member、manager — を持ち、キーを発行したメンバーのロールが上限になります。非メンバーは非公開プロジェクトのパスで 404 unfound_resource（403 ではなく）を受け取るので、プロジェクト ID は列挙できません。
自己記述型エンドポイント
Section titled “自己記述型エンドポイント”| Method | Path | 説明 |
|---|---|---|
| GET | /openapi.json | ライブの OpenAPI 3 仕様（リクエストボディを含む）。認証不要。 |
| GET | /docs | Swagger UI。認証不要。 |
| GET | /meta | 呼び出し元のアイデンティティ（auth.kind/key_id/agent_id/project_id）+ ストーリータイプの遷移グラフ。認証済み（任意の有効なキー。プロジェクトスコープではない）。最初にこれを呼びます。 |
| GET | /api/health · /api/config | 死活確認と、デプロイの公開設定（シングル組織モード、有効なオプション機能、インスタンス名）。認証不要、/v1 の外。 |
Auth（/api/auth/*、/v1 の外）
Section titled “Auth（/api/auth/*、/v1 の外）”セッション用のエンドポイントで、特記がない限り認証不要です。SPA がこれらを使います。スクリプトは通常、代わりに API キーを使います。
| Method | Path | 説明 |
|---|---|---|
| POST | /auth/register | 新規アカウントを登録 — reCAPTCHA で保護。その後アカウントは SMS チャレンジを通過する |
| POST | /auth/sms/challenge · /auth/sms/status · /auth/sms/bypass | サインアップ用の SMS コードを送信 / 確認（バイパスはオペレーター限定） |
| GET | /auth/config | デプロイが提供するサインイン方法 |
| POST | /auth/login | メール + パスワードでサインイン。セッション JWT、または TOTP チャレンジを返す |
| POST | /auth/login/totp | 認証アプリのコードまたはリカバリーコードでサインインを完了 |
| POST | /auth/passkey/login/start · /auth/passkey/login/finish | パスワードレスの WebAuthn サインイン |
| GET | /auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange | GitHub または Google による OAuth サインイン |
| POST | /auth/refresh · /auth/refresh/revoke | リフレッシュトークンをローテーション / 取り消す |
| POST | /auth/logout | サインアウト（認証が必要。このセッションのリフレッシュトークンを取り消す） |
| POST | /auth/forgot-password · /auth/reset-password | リセットメールを要求 / リセットトークンを使用 |
| POST | /auth/accept-invite/lookup · /auth/accept-invite | 招待トークンを解決 → メールアドレス / プロジェクトの招待を受け入れる（認証後） |
| POST | /auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm | GitHub または Google アカウントを既存のアカウントに接続する、または 2 つのアカウントを統合する |
| POST | /auth/email_addresses/primary/preview · …/primary/confirm | メールで届いた確認リンクから、プライマリメールアドレスの変更を完了する |
アカウント / アイデンティティ
Section titled “アカウント / アイデンティティ”これらは呼び出し元に作用し、プロジェクトロールは不要です。メンバーのアイデンティティが必要で、エージェントキーは 401 になります（エージェントは /agent/me を使います）。認証情報を変更する呼び出し — パスワード、TOTP、パスキー、アカウント削除、メールアドレスの変更、トークンの再生成 — にはブラウザセッションが必要で、API キーでは 403 になります。
| Method | Path | 説明 |
|---|---|---|
| GET | /me | 現在のユーザープロフィール |
| PUT | /me | プロフィールを更新 |
| DELETE | /me | アカウントを削除 — 他のメンバーがいる組織またはプロジェクトの唯一のオーナーである間は拒否される |
| GET | /me/deletion-impact | アカウントを削除すると何が消えるか、そして何が削除を妨げているか |
| PUT | /me/password | パスワードを変更 |
| PUT | /me/settings | 設定を更新（テーマ、通知設定） |
| POST / DELETE | /me/avatar | アバターをアップロード（multipart）/ 削除 |
| POST | /me/api-token/regenerate | すべてのセッションをサインアウトし、新しいセッショントークンを返す。API キーには影響しない |
| GET / POST | /me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary | 自分のメールアドレス。接続済みプロバイダーのアドレスを代替アドレスとして採用。プライマリの変更を要求（メールで確認） |
| GET | /me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link | 接続済みのサインインアカウント（GitHub、Google）: 一覧、切断、リンクの開始 |
| GET | /me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id} | ユーザー（ea_user_）API キーを管理 |
| GET | /me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable | 2 要素認証（TOTP）の登録。verify はリカバリーコードを一度だけ返す |
| GET | /me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id} | パスキーの登録と削除 |
| GET | /me/oauth_grants · DELETE /me/oauth_grants/{grant_id} | 接続済みアプリ — あなたが認可した MCP クライアントと OAuth アプリ |
| GET | /me/activity | 全プロジェクトにわたるあなたのアクティビティ |
| GET | /me/stories | トークンが到達できるすべてのプロジェクトで、あなたがオーナー・リクエスター・フォロワーであるストーリー — role=owned|requested|following、state=、cursor= / limit=（最大 200） |
| GET | /me/mentions · POST /me/mentions/{mention_id}/ack | @メンション受信箱（unacked=true で絞り込み）と既読確認 — 下記の通知フィードにも統合されている |
| GET | /me/data-export | あなたのデータの GDPR セルフエクスポート |
| GET | /me/consent · POST /me/consent | 同意を読み取り / 記録（{ consent_type, granted }） |
| GET | /legal/pending · POST /legal/accept | 保留中のクリックラップ文書 / 受け入れを記録 |
| GET / PUT | /agent/me | エージェントキー自身のアイデンティティとプロフィール。エージェントが読み取り・編集できる（/me のエージェント側の対応物） |
| POST | /api/contact · /api/v1/feedback · /api/v1/feedback/with-screenshot | お問い合わせ + アプリ内フィードバック。IP ごとにレート制限あり |
参照データ（認証不要）
Section titled “参照データ（認証不要）”ストーリーの作成/見積もり時に使われるシードルックアップ。安定した ID。
| Method | Path | 説明 |
|---|---|---|
| GET | /story_types | feature, bug, chore, release（+ allow_points） |
| GET | /story_states | unstarted … accepted, rejected |
| GET | /effort_scales | 利用可能な見積もりスケール |
| GET | /effort_scales/{scale_id}/values | スケール内のポイント値 |
| GET | /priority_scales · /priority_scales/{scale_id}/values | 優先度スケールとその値（ストーリーの priority_id はここで解決される） |
ホスティング版サービスのみ — セルフホストのインストールはシングル組織モードで動作し、これらをマウントしません（組織一覧を除く）。ロールは組織ロールです: owner、admin、member。
| Method | Path | 説明 |
|---|---|---|
| GET / POST | /organizations | 自分の組織を一覧 / 作成 |
| GET / PUT / DELETE | /organizations/{oid} | 読み取り、名前変更（名前 + slug。owner または admin）、削除 |
| GET / POST | /organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id} | メンバーと招待。招待にはロールの上限がある（呼び出し元のロールを超えない。owner は招待では付与されない） |
| POST | /organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove | 最大 200 人のメンバーのロールを一括変更、または一括削除。全件か無し: 最後の owner を外す、またはプロジェクトの所有者がいなくなるバッチは丸ごと拒否される。reassign_confirmed を指定すると、代わりに自分がそれらのプロジェクトの所有者になる |
| DELETE | /organizations/{oid}/invitations/{invitation_id} | 保留中の招待を取り消す |
| POST | /organizations/{oid}/transfer-ownership | owner ロールを別のメンバーに引き渡す |
| GET | /organization-invitations/{token} · POST …/{token}/accept | メールで届いた組織の招待を解決 / 受け入れる |
| GET | /organizations/{oid}/export · POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download | owner 限定の組織エクスポート: SQL ダンプとすべての添付ファイルを含む zip を、ジョブとして実行 |
プロジェクト
Section titled “プロジェクト”| Method | Path | 説明 |
|---|---|---|
| GET | /projects | あなたのプロジェクトを一覧表示（limit ≤ 200） |
| POST | /projects | プロジェクトを作成 |
| GET | /projects/{id} | プロジェクト詳細を取得 (viewer) |
| PUT | /projects/{id} | プロジェクト設定を更新 (manager) |
| DELETE | /projects/{id} | プロジェクトを削除 (manager) |
| POST / DELETE | /projects/{id}/pin | プロジェクト一覧でプロジェクトをピン留め / ピン留め解除 |
| POST | /projects/{id}/transfer-organization | プロジェクトを別の組織に移動 — 呼び出し元はプロジェクトのマネージャーであり、移動先の組織で owner または admin である必要がある |
| POST | /projects/{id}/slack/test | プロジェクトの Slack フィードにテストメッセージを送信 (manager) |
| GET / POST | /projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed | 公開ショーケースプロジェクト: 引き取れるかを確認、引き取る、データを投入する（データ投入はプロダクト管理者向け。それ以外は 404） |
| GET | /projects/{id}/audit-log | 監査ログの読み取り — プロジェクト履歴に加え、surface= によるストーリー別 / Epic 別のアクティビティ。アクセスは surface により異なる（下記参照） |
| GET | /projects/{id}/events | カーソルでページ分割されたイベントストリーム (member) — イベント を参照 |
監査ログのクエリパラメータ: event_type=（単一タイプまたはカンマ区切りリスト）、limit=（デフォルト 50、1000 に制限）、before=（keyset カーソル <ISO-8601>|<audit_id> — 前のページの next_cursor を渡す）、surface=（project_history、story_activities、epic_activities）、target_id=（ストーリー/Epic の id — surface=story_activities または epic_activities のとき必須）。アクセス: フィルタなしのログは (manager)。surface=project_history は (viewer) で、プロジェクトがメールアドレスを非表示にしている場合はメンバーのメールアドレスがマスクされる。story_activities / epic_activities はプロジェクトの任意のメンバーが読め、公開プロジェクトでは匿名でも読める（アクターの PII はマスクされる）。
メンバー、エージェント、エージェントキー
Section titled “メンバー、エージェント、エージェントキー”| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/memberships | メンバーを一覧表示 (viewer) |
| POST | /projects/{id}/memberships | メンバーをメールで招待 (manager) |
| PUT | /projects/{id}/memberships/{mid} | ロールを更新 (manager) |
| DELETE | /projects/{id}/memberships/{mid} | メンバーを削除 (manager) |
| POST | /projects/{id}/memberships/bulk-role · …/memberships/bulk-remove | 多くのメンバーのロールを一括変更、または一括削除 (manager) |
| GET | /projects/{id}/addable-members · POST /projects/{id}/members/add-existing | まだプロジェクトにいない組織メンバー / メール招待なしで 1 人追加 — (manager) かつ組織の owner または admin |
| POST | /projects/{id}/members/join | 組織の owner または admin が、自組織のプロジェクトに manager として参加する、または自分を manager に昇格させる（プロジェクト一覧の Make me owner アクション） |
| GET / POST | /projects/{id}/agent_keys | 一覧 (manager) / エージェントキーを発行 — プロジェクトのキー作成者ロールのポリシーに含まれるロールの人。エージェントキーは発行できない |
| PUT / DELETE | /projects/{id}/agent_keys/{kid} | キーの名前、ロール、レスポンスヒントを編集 / 取り消す (manager) |
| GET | /projects/{id}/agent_keys/onboarding | オンボーディング一式: 一般的なエージェントクライアント向けのプロンプトと設定ファイル |
| GET | /projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid} | プロジェクトのエージェントとそのプロフィール（名前、イニシャル、説明、色）。DELETE はエージェントとそのすべてのキーを取り消す — manager またはエージェントの作成者 |
| POST | /projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar | エージェントのキーをローテーション（アイデンティティと履歴は保持）/ アバターをアップロード |
すべてのストーリー書き込みは member ロールを必要とします。日付をさかのぼらせたストーリー、インポート元情報（import_source / import_external_id）、または外部のオーナーやリクエスターを伴うストーリーの作成には (manager) が必要です。
| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/stories | ストーリーを一覧表示（ページ分割、フィルター可能） (viewer) |
| POST | /projects/{id}/stories | ストーリーを作成 |
| GET | /projects/{id}/stories/{sid} | 1 つのストーリーを取得 (viewer) |
| PUT | /projects/{id}/stories/{sid} | ストーリーを更新 |
| DELETE | /projects/{id}/stories/{sid} | ストーリーを削除 |
| POST | /projects/{id}/stories/{sid}/transitions | 検証付きで状態を変更 |
| POST | /projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart | 納品済みのストーリーを却下 / 却下されたストーリーを started に戻す（/transitions にとって rejected は終端状態） |
| POST | /projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive | 1 つのストーリーをアーカイブ / アーカイブ解除 |
| POST | /projects/{id}/stories/bulk-unarchive | 多くのストーリーをアーカイブ解除 |
| POST | /projects/{id}/stories/bulk_transition | 多くのストーリー（1〜100）を一度に遷移 |
| POST | /projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move | 多くのストーリーをアーカイブ、削除、複製、または移動（パネル / 位置へ） |
| POST | /projects/{id}/stories/{sid}/duplicate | 1 つのストーリーを複製 |
| POST / DELETE | /projects/{id}/stories/{sid}/epics · …/epics/{eid} | ストーリーの Epic への所属 |
| GET | /short-links/{code} · /story-references | /s/<code> 短縮リンクをそのストーリーに解決 / 最大 100 件の参照 — codes=（カンマ区切りの短縮リンクコード）と ids=（カンマ区切りの project_id:story_id）— を、呼び出し元が読めるストーリーに解決 |
ストーリー一覧のクエリパラメータ: archived=（exclude デフォルト / include / only — 3 値のアーカイブフィルター。非推奨の include_archived=true に取って代わり、後者は現在 archived=include のエイリアスです）、include_done=true（過去のイテレーションに凍結された Done パネルのストーリーを含める。デフォルトでは除外）。ページング（cursor= / limit= / offset=）と部分フィールドセット（fields=）は、ページネーション と フィールドの射影 に従います。
作成（POST …/stories）: { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }。estimate はスケール値の ラベル を文字列で指定します（"3"、"13"）。JSON の数値は拒否されます。labels は ["auth"] または [{ "name": "auth" }] を受け付けます。未知のラベルは作成されます。デフォルト: story_type=feature、current_state=unstarted。
更新（PUT …/stories/{sid}）: 同じフィールド、すべて任意、加えて "position"（float）、"force_state_change"（bool）、"expected_version"（整数、ストーリーの version — そのバージョン以降に説明が変更されていた場合、説明の保存は 409 stale_write で拒否されます）。旧来の "expected_updated_at"（RFC 3339）は非推奨で、あと 1 リリースだけ動作します。説明と一緒に expected_version なしで送信した場合、ストーリーの updated_at と一致しなければ保存は 409 stale_write で拒否されます。ストーリーの書き込みは、ストーリーの ETag に対する If-Match にも従います。一致しない場合は 412 precondition_failed です。
遷移（POST …/transitions）: { "to": "<state>" }。フィールドは to です。{ story_id, state } を返します。不正な移動 → details: { from, to, allowed } 付きの 422 invalid_transition。
一括遷移（POST …/bulk_transition）: { "story_ids": [int,…] (1–100), "to": "<state>" }。各ストーリーは独立して判断されます。{ results: [ { id, status: "ok" } | { id, status: "failed", error } ] } を返します。
ストーリーのサブリソース
Section titled “ストーリーのサブリソース”すべて member。ほとんどの List/GET は (viewer) です。添付ファイルまたはリンク添付の削除には、そのアップロード者または (manager) が必要です。
| Method | Path | ボディ / 注記 |
|---|---|---|
| GET / POST | /projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid} | { description (or task_desc), complete?, task_order? } |
| GET / POST | /projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid} | { text (or comment_text) } または { comment_emoji }。GET は fields=（許可リスト: comment_id、story_comment_id、story_id、comment_text、comment_emoji、member、created）に加えて cursor= / limit=（≤ 200）/ order=asc|desc を取る |
| GET / POST | /projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid} | { blocker_desc, resolved? } |
| GET / POST | /projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid} | 作成: { url, link_type?, title? }。更新: { url, title? } — link_type ∈ relates_to、duplicates、blocks、is_blocked_by、pull_request、branch、other。GitHub の /pull/ と /tree/ の URL には自動的に種別が付く |
| GET / POST | /projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid} | 作成: { reviewer_id? / reviewer_agent_id?, comment? } — 両方を省略すると自分自身を割り当てる。更新: { status, comment? } |
| GET / POST | /projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid} | { member_id? / agent_id? } — 両方を省略すると呼び出し元を追加 |
| GET / POST | /projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid} | { member_id? / agent_id? } |
| GET / POST | /projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid} | { label_id } — 既存のプロジェクトラベル。ラベルは POST /projects/{id}/labels で作成するか、ストーリーの PUT で labels を送る |
| GET / POST | /projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid} | multipart アップロード — 動画 ≤ 200 MB、PDF / Word / Excel ≤ 25 MB、画像 / CSV / テキスト ≤ 10 MB。一覧は (viewer) |
| GET / POST | /projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid} | リンク添付 — コードリンクとしてではなく、ファイル添付と並べて保持される外部 URL |
| GET | /attachments/{token} · /api/v1/avatars/{token} | 添付ファイルまたはアバターのトークン指定による読み取り — API が返す URL。X-TrackerToken は不要 |
ストーリーと同じ形で、ステートマシンがないものです。書き込みと、コメント・オーナー・フォロワーの一覧は member。Epic の一覧、単一の Epic、添付ファイルの一覧は (viewer)。
| Method | Path | 説明 |
|---|---|---|
| GET / POST | /projects/{id}/epics · GET / PUT / DELETE …/epics/{eid} | Epic は名前、Markdown の説明、そしてストーリーを束ねる裏付けラベルを持つ |
| GET / POST / PUT / DELETE | …/epics/{eid}/comments · …/comments/{cid} | Epic のコメント |
| GET / POST / DELETE | …/epics/{eid}/owners · …/followers（+ /agents/{aid} の各バリアント） | オーナーとフォロワー（メンバーまたはエージェント）— Epic のオーナーはそのストーリーに伝播する |
| GET / POST / DELETE | …/epics/{eid}/attachments (+ /json) · …/link-attachments | 添付ファイル。上限はストーリーと同じ |
| GET | /projects/{id}/analytics/epics · …/analytics/epics/{eid} | Epic ごとの進捗: バーンアップ、スループット、健全性、予測 (viewer) |
書き込みは member、読み取りは (viewer)。
| Method | Path | 説明 |
|---|---|---|
| GET / POST | /projects/{id}/labels | ラベルを一覧 / 作成 |
| GET / PUT / DELETE | /projects/{id}/labels/{lid} | ラベルを読み取り / 更新 / 削除 |
| POST | /projects/{id}/labels/{lid}/archive | ラベルをアーカイブ（ソフト非表示） |
イテレーション
Section titled “イテレーション”読み取りはすべてのプロジェクトロールに開かれており、公開プロジェクトでは匿名でも可能です。
| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/iterations | イテレーションを一覧表示（1 ページあたり ≤ 500。ETag を伴い、切り詰められた場合は X-Tracker-Pagination-* 継続ヘッダーも伴う） |
| GET | /projects/{id}/iterations/{itid} | 1 つのイテレーション |
| GET | /projects/{id}/iterations/first-preview | シード書き込みが作成するイテレーション、または現在のイテレーションが存在する場合はそのイテレーションの期間、予測ベロシティ、Backlog からの充填数 (member) |
| POST | /projects/{id}/iterations | 手動イテレーションを作成 (manager) |
| DELETE | /projects/{id}/iterations/{itid} | イテレーションを削除 (manager) |
| PUT | /projects/{id}/iterations/{itid}/velocity | プロジェクトの戦略を変えずに、1 つのイテレーションのベロシティを上書き (manager) |
| GET | /projects/{id}/iterations/{itid}/done-stories | 終了したイテレーションの受け入れ済みストーリー（ページ分割） |
検索、メトリクス、設定
Section titled “検索、メトリクス、設定”| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/search?q=… | 強力な検索 — 全文 + ファセット / 日付範囲 / 人物の修飾子（GitHub スタイルの DSL）。{ results, total, limit, offset } を返す。query は q のエイリアス。limit=（デフォルト 50、最大 1000）/ offset= でページング。sort= は relevance（デフォルト）、created、created_asc、state、updated で並べ替え。(viewer) — ガイド を参照 |
| GET | /projects/{id}/metrics/{velocity,burndown,story-types,contributors} | Metrics ページの系列データ (viewer)。Epic のメトリクスは上記の /analytics/epics にある |
| GET | /projects/{id}/backlog/grouping | Backlog の予測イテレーショングループ (viewer) |
| GET / PUT | /projects/{id}/preferences | このプロジェクトに対するあなたのボード設定 — 任意のプロジェクトロール、自分の行のみ |
| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/events | カーソルでページ分割されたイベントストリーム (member) — viewer は 403 を受け取る |
クエリパラメータ: since_id=<event_id>（since は旧来のエイリアス。両方を送った場合は since_id が優先）、types=story.created,story.transitioned,comment.added,…、limit=（デフォルト 100、≤ 500）、cursor=。レスポンスは { items, next_since_id, next_cursor } です: next_since_id を保存し、since_id として渡し返すと再開します。最後のページでは next_cursor は null です。
アプリ内通知の統合フィード: ファーストクラスの通知行（レビュー依頼、ストーリーのアクティビティ、招待など）を @メンション受信箱と統合し、新しい順の 1 本のストリームにまとめたものです。フィードの id はソースを示すプレフィックス付きです（nt-… / sc-… / ec-…）。メンバーセッションと ea_user_* キーはメンバー側の行を、ea_agent_* キーはエージェント側の行を読み取ります。
| Method | Path | 説明 |
|---|---|---|
| GET | /me/notifications | 自分の通知フィード。フィルタ: unread=true、since_id=、kind=（mentions / reviews / stories / invitations）。ページングは cursor= / limit= |
| GET | /me/notifications/unread-count | 未読数の合計 — { unread_count, by_category: { mentions, reviews, stories, invitations } } |
| POST | /me/notifications/read-all | すべて既読にする。最新のカウントを返します |
| POST | /me/notifications/{id}/ack | 1 件を既読にする（冪等） |
| POST | /me/notifications/{id}/accept | フィードからプロジェクト / 組織への招待を承諾（メンバートークンのみ） |
| POST | /me/notifications/{id}/decline | プロジェクト / 組織への招待を辞退（メンバートークンのみ） |
| GET | /me/notifications/resolve-invite?token=… | メールで届いた招待トークンを自分の通知 id に解決 — { "id": "nt-…" } または { "id": null } |
| GET | /me/notifications/stream | ライブプッシュ — Server-Sent Events（text/event-stream）。下記参照 |
stream エンドポイントは JSON エンドポイントではないため、OpenAPI 仕様には含まれません。接続を開いたまま維持し、新着があるたびにペイロードなしのフレーム（{"type":"notification","kind":…}）を送出して、クライアントにフィードの再取得を促します。接続はサーバー側で 45 分で打ち切られます — 再接続して再認証してください。メンバーセッションと ea_user_* キーのみ。ea_agent_* キーは 403 になります。
インポート (manager)
Section titled “インポート (manager)”| Method | Path | 説明 |
|---|---|---|
| POST | /projects/{id}/import | ファイルソース: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat。Multipart file=。同期 — 結果の件数で応答する。 |
| POST | /projects/{id}/import/json | JSON ボディ。source=github はファイル不要 — owner、repo、任意の token、およびオプトインフラグ include_pull_requests / include_milestones / include_releases / include_dependencies、および include_comments（既定 true）。ファイル系ソースは file_base64 を送る。非同期: 202 { import_id, status } を返す。サーバーは GitHub の GraphQL API 経由で取得し、この API は匿名の呼び出し元を拒否するため、GitHub には常にトークンが渡ります — あなたのものか、デプロイの共有トークンです。ガイドを参照してください。 |
| GET | /projects/{id}/imports/{import_id} | ジョブをポーリング: status は pending → fetching → writing → done | failed と進み、取得中は progress_current / progress_total が、done になると結果の件数が得られる |
JSON インポートはプロジェクトごとに一度に 1 つだけ実行されます。実行中に 2 つ目の POST …/import/json を送ると 409 import_already_running になります。check_unpointed_estimates: true を付けると（ファイルソース用。github では無視されます）、プロジェクトがポイントを付けないバグまたは雑務の見積もりを含むファイルは、ジョブが始まる前に 409 import_unpointed_estimates と details.count で拒否されます。フラグがない場合、インポートはそれらの見積もりを破棄し、結果の warnings に { code: "estimates_unpointed_dropped", count } を報告します。dry_run: true（JSON ボディまたは dry_run=true multipart）は任意のソースをプレビューします。解析・解決・重複排除を行い、実際のインポートと同じ { imported, skipped, errors, unmatched } の件数を返してからロールバックします — 何も書き込まれません。上限: ファイル 10 MiB（400 import_too_large）、およびファイル系ソースではインポートあたり 5,000 ストーリー（400 import_too_many_records）。何も書き込まれません。16 MiB を超えるリクエストボディは、それより前に 413 request_too_large で拒否されます。GitHub ソースに上限はありません — 単一トランザクションではなく分割してコミットするためです。再インポートはソース id ごとに冪等です — すでにインポート済みの行は重複せずスキップされます。
エクスポート
Section titled “エクスポート”| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/export/formats | 登録済みフォーマット: { id, name, content_type, drops, includes_archived }。任意のプロジェクトロール。 |
| GET | /projects/{id}/export/{format} | 1 つをダウンロード (manager)。交換用: eat（フル忠実度）、jira、pivotal、shortcut、trello、asana、gitlab、linear、plane、plane_json。ドキュメント: pdf、docx。 |
| GET | /projects/{id}/export/attachments | すべての添付ファイルを閲覧可能な 1 つの zip として（ファイルは元の名前を保持。JSON + CSV マニフェスト） (manager)。 |
ドキュメントエクスポート（pdf、docx）は追加のクエリパラメータを取ります: page_size=（letter デフォルト / a4 / legal / folio）、from= / to=（ストーリーウィンドウの範囲 — RFC 3339 または素の YYYY-MM-DD。ストーリーは、その created または completed_at が範囲内に入る場合に対象になります）、include_icebox= / include_backlog=（どちらもデフォルト false。したがって共有可能なエクスポートにはスケジュール済み / 進行中の作業のみが表示されます）。交換用の CSV フォーマットはこれらを無視します。
バックアップと復元 (manager)
Section titled “バックアップと復元 (manager)”| Method | Path | 説明 |
|---|---|---|
| GET / POST | /projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health | スナップショットの一覧、今すぐ 1 つ取得、1 つを読み取り、そして保持状況のヘルスサマリー |
| POST | /projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id} | スナップショット全体、またはその中の選択したテーブルを復元し、復元の状況をポーリング |
これらの POST は sensitive のレート制限ティア（下記）に属します。
MCP と OAuth プロバイダー
Section titled “MCP と OAuth プロバイダー”East Agile Tracker は MCP クライアント向けの OAuth 2.1 プロバイダーです。クライアントは /.well-known/oauth-authorization-server と /.well-known/oauth-protected-resource/mcp でこれを発見し、あなたを /oauth/authorize（同意ページ）に送り、/oauth/token でコードを交換し、得られた ea_mcp_* トークンを使って /mcp で MCP を話します。付与（グラント）は /me/oauth_grants で一覧・取り消しできます。プロバイダーのエンドポイントには独自のレート制限ティアがあります。
書き込みエンドポイント（POST、PUT、DELETE）は Idempotency-Key ヘッダーを受け付けます。同じキー + 同じボディはキャッシュされたレスポンスを再生します（24 時間のウィンドウ）。同じキー + 異なる ボディは 409 idempotency_conflict を返します。キーはそれを送信した認証情報にスコープされます。GET/HEAD/OPTIONS、/openapi.json と /docs、/api/auth/*、/mcp、/attachments を含む任意のパス、または任意の multipart/* リクエストには適用されません。認証情報のないリクエストは決してキャッシュされません。ドメインとしての応答に至らずに終わったレスポンス — 401、403、404、429、およびすべての 5xx — は決してキャッシュされないため、これらの後の再試行はハンドラーに到達します。400、409、412、422 はドメインとしての応答であり、成功と同様に再生されます。
ページネーション
Section titled “ページネーション”リスト系エンドポイントは cursor=<opaque> と limit=<n> を受け付けます。設定された場合、レスポンスは { "items": [...], "next_cursor": "<str|null>" } です。next_cursor を渡し返してページングします。limit の上限はエンドポイントごとに異なります: ストーリー、コメント、プロジェクトは 200、イベントは 500、監査ログは 1000 です。検索はカーソルの代わりに limit（≤ 1000）と offset でページングし、{ results, total, limit, offset } を返します。
cursor/limit なしの通常のリストがレスポンスを切り詰めた場合は、ヘッダーでそれを示します — X-Tracker-Pagination-Truncated、X-Tracker-Pagination-Limit、X-Tracker-Pagination-Offset、X-Tracker-Pagination-Next-Offset。次のページを取得するには、最後のものを offset= として渡し返します。総件数のヘッダーはありません。
フィールドの射影
Section titled “フィールドの射影”ストーリー、コメント、プロジェクトの一覧は、特定のフィールドのみを返すために fields=（カンマ区切り）を受け付けます。リソースの id は常に含まれます（story_id、story_comment_id と comment_id、project_id）。未知のフィールド名は、問題のある名前を details.fields に入れた 400 validation_failed を返します。
GET /projects/123/stories?fields=story_id,name,current_state,ownersすべての JSON エラーは code と error を持ち、一部は details を加えます。
{ "code": "invalid_transition", "error": "Cannot move story from `unstarted` to `accepted`", "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] } }| Status | code | 発生する場合 |
|---|---|---|
| 400 | invalid_parameter | 不正な入力。メッセージは error 内。フィールド検証（空白/長さ/null バイト/メール）は details.fields と details.constraint を付加する。details がないのは単純な不正リクエストエラーのみ |
| 400 | validation_failed | 構造化された入力エラー。details.fields は問題のあるフィールド名の 配列 |
| 400 | ドメインコード | 独自のコードを持ち details のない、ルート固有の拒否 — 例: unsupported_export_format、import_too_large、import_unknown_source |
| 401 | unauthenticated | トークンの欠落/無効 |
| 403 | unauthorized_operation | 認証済みだがロールが不十分 |
| 404 | unfound_resource | 見つからない — 非メンバーにも返される |
| 409 | conflict | リソースの競合（例: 重複） |
| 409 | idempotency_conflict | Idempotency-Key が異なるボディで再利用された |
| 409 | stale_write · import_already_running · import_unpointed_estimates | expected_version 以降に説明が変更された（または expected_updated_at が一致しなくなった） · インポートがすでに実行中 · ファイルに、プロジェクトがポイントを付けないバグまたは雑務の見積もりがある（details.count） |
| 412 | precondition_failed | If-Match がリソースの現在の ETag と一致しなかった。details が expected と current を運ぶ |
| 413 | request_too_large | ボディがルートのサイズ上限を超えている |
| 422 | invalid_transition | 不正な状態移動。details が { from, to, allowed } を運ぶ |
| 429 | rate_limited | レート制限のあるルートで、この IP からのリクエストが多すぎる。Retry-After ヘッダー付き |
| 500 | internal_error | サーバー障害 — 汎用メッセージ。再試行して安全 |
| 502 | upstream_error | ルートが依存するサービス（例: GitHub）が失敗した |
| 503 | not_configured | このルートに必要な連携（SMS、オブジェクトストレージ、…）がデプロイに設定されていない |
details.fields はフィールド名の JSON 配列（例: ["to"]）で、max のような追加のキーを伴うこともあります。フィールド→メッセージのマップはありません。
{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }クライアント IP ごとに、少数のルートに対して適用されます。それ以外の認証済み API トラフィックにはレート制限はありません。デフォルト値（各ペアは持続レートとバーストで、オペレーターが調整可能）:
- Auth —
/api/auth/*: 0.5 req/s、バースト 20。 - OAuth プロバイダー —
/oauth/*: 1 req/s、バースト 60。 - Public —
/api/contact: 0.2 req/s、バースト 10。 - Feedback —
/api/v1/feedbackと/api/v1/feedback/with-screenshot: 3 段階の制限が重なる — 送信は 15 秒に 1 回、1 時間に 10 回、1 日に 36 回まで。 - Avatars — 認証不要のアバターリダイレクト: 20 req/s、バースト 200。
- Sensitive — バックアップと復元の
POST: 約 0.002 req/s、バースト 5。
制限を超えると、Retry-After ヘッダーと標準の JSON エラーエンベロープ（code: "rate_limited"）を伴う 429 が返されます。