完全な REST エンドポイントリファレンスです。チュートリアルと例については API ガイド を参照してください。
プロジェクトの member が Web UI でできることはすべてここで利用できます — SPA はこの同じ API を消費しています。manager ロールを必要とする操作は (manager) とマークされています。それ以外はプロジェクトメンバーシップのみ（または、(viewer) とマークされた読み取りについては任意のアクセスレベル）を必要とします。以下の表はサーバーがマウントするすべてのルートグループを挙げています。1 行で要約されているものは、ライブの openapi.json に完全に記述されています。
https://eastagiletracker.com/api/v1https://api.eastagiletracker.com/api/v1 は同一の API を提供します。すべてのリクエストとレスポンスは JSON です。ただし、multipart を受け付けるいくつかのファイルアップロードエンドポイントを除きます。
2 つのグループは 1 階層上、/api/v1 ではなく /api の下にあります: 認証サーフェス（/api/auth/*）と公開フォーム（/api/contact、/api/feedback）です。これらを /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 | 招待トークンを解決 → メールアドレス / プロジェクトの招待を受け入れる（認証後） |
アカウント / アイデンティティ
Section titled “アカウント / アイデンティティ”これらは呼び出し元に作用し、有効なキーのみを必要とします（プロジェクトロールは不要）。
| Method | Path | 説明 |
|---|---|---|
| GET | /me | 現在のユーザープロフィール |
| PUT | /me | プロフィールを更新 |
| DELETE | /me | アカウントを削除 — 他のメンバーがいる組織またはプロジェクトの唯一のオーナーである間は拒否される |
| GET | /me/deletion-impact | アカウントを削除すると何が消えるか、そして何が削除を妨げているか |
| PUT | /me/password | パスワードを変更 |
| PUT | /me/settings | 設定を更新（テーマ、通知設定） |
| POST | /me/avatar | アバターをアップロード（multipart） |
| POST | /me/api-token/regenerate | API トークンをローテーション — 既存のセッション/キーを無効化 |
| 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/feedback · /api/feedback/with-screenshot | お問い合わせ + アプリ内フィードバック。/v1 の外。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 ロールを別のメンバーに引き渡す |
| PUT | /organizations/{oid}/memberships/{member_id}/anonymization | メンバーの名前 / メール / アバターを組織全体でマスク |
| GET | /organization-invitations/{token} · POST …/{token}/accept | メールで届いた組織の招待を解決 / 受け入れる |
| POST | /organizations/{oid}/export · GET / 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 | /projects/{id}/pin | プロジェクト一覧でプロジェクトをピン留め / ピン留め解除 |
| POST | /projects/{id}/transfer-organization | プロジェクトを別の組織に移動 (manager) |
| POST | /projects/{id}/slack/test | プロジェクトの Slack フィードにテストメッセージを送信 (manager) |
| GET / POST | /projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed | 公開ショーケースプロジェクト: 引き取れるかを確認、引き取る、データを投入する |
| GET | /projects/{id}/audit-log | 監査ログの読み取り — プロジェクト履歴に加え、surface= によるストーリー別 / Epic 別のアクティビティ。アクセスは surface により異なる（下記参照） |
| GET | /projects/{id}/events | カーソルでページ分割されたイベントストリーム (member) — イベント を参照 |
監査ログのクエリパラメータ: event_type=（単一タイプまたはカンマ区切りリスト）、limit=（≤ 1000）、before=（keyset カーソル、ISO-8601 の created_at）、surface=（project_history、story_activities、epic_activities）、target_id=（ストーリー/Epic の id — surface=story_activities または epic_activities のとき必須）。アクセス: フィルタなしのログと surface=project_history は (manager)。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) |
| GET | /projects/{id}/addable-members · POST /projects/{id}/members/add-existing | まだプロジェクトにいない組織メンバー / メール招待なしで 1 人追加 (manager) |
| POST | /projects/{id}/members/join | 組織の owner または admin が、自組織のプロジェクトに manager として参加する、または自分を manager に昇格させる（プロジェクト一覧の Make me owner アクション） |
| PUT | /projects/{id}/members/{mid}/anonymization | このプロジェクトでメンバーの名前 / メール / アバターをマスク (manager) |
| GET / POST | /projects/{id}/agent_keys | エージェントキーを一覧 / 発行 — manager、またはプロジェクトのキー作成者ロールのポリシーが認めるロール |
| DELETE | /projects/{id}/agent_keys/{kid} | エージェントキーを取り消す |
| GET | /projects/{id}/agent_keys/onboarding | オンボーディング一式: 一般的なエージェントクライアント向けのプロンプトと設定ファイル |
| GET | /projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid} | プロジェクトのエージェントとそのプロフィール（名前、イニシャル、説明、色） |
| POST | /projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar | エージェントのキーをローテーション（アイデンティティと履歴は保持）/ アバターをアップロード |
すべてのストーリー書き込みは member ロールを必要とします。
| 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_transition | 多くのストーリー（1〜100）を一度に遷移 |
| POST | /projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move | 多くのストーリーをアーカイブ、削除、複製、または移動（パネル / 位置へ） |
| POST | /projects/{id}/stories/{sid}/duplicate | 1 つのストーリーを複製 |
| GET / POST / DELETE | /projects/{id}/stories/{sid}/epics · …/epics/{eid} | ストーリーの Epic への所属 |
| GET | /short-links/{code} · /story-references | /s/<code> 短縮リンクをそのストーリーに解決 / 最大 100 件のストーリー参照（#id、URL）を、呼び出し元が読めるストーリーに解決 |
ストーリー一覧のクエリパラメータ: 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_updated_at"（RFC 3339 — 読み取った後にストーリーが変更されていた場合、説明の保存は 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) です。
| 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? } — 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} | { name } |
| 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/avatars/{token} | 添付ファイルまたはアバターのトークン指定による読み取り — API が返す URL。X-TrackerToken は不要 |
ストーリーと同じ形で、ステートマシンがないものです。書き込みは member、読み取りは (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 | ラベルを一覧 / 作成 |
| 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 | 最初のイテレーションに割り当てられる日付。作成時の確認画面に表示される |
| POST | /projects/{id}/iterations | 手動イテレーションを作成 (member) |
| 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=<event_id>、types=story.created,story.transitioned,comment.added,…、limit=（≤ 500）、cursor=。レスポンスには next_cursor が含まれます。最後に見た event_id を since として渡すと再開します。
アプリ内通知の統合フィード: ファーストクラスの通知行（レビュー依頼、ストーリーのアクティビティ、招待など）を @メンション受信箱と統合し、新しい順の 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。ファイル系ソースは 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 になると結果の件数が得られる |
インポートはプロジェクトごとに一度に 1 つだけ実行されます。実行中に 2 つ目の POST を送ると 409 import_already_running になります。dry_run: true（JSON ボディまたは dry_run=true multipart）は任意のソースをプレビューします。解析・解決・重複排除を行い、実際のインポートと同じ { imported, skipped, errors, unmatched } の件数を返してからロールバックします — 何も書き込まれません。上限: ボディ 10 MiB、およびファイル系ソースではインポートあたり 5,000 ストーリー（どちらかを超えると → 400、何も書き込まれません）。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 つを読み取り、そして保持状況のヘルスサマリー |
| GET / 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 で一覧・取り消しできます。プロバイダーのエンドポイントには独自のレート制限ティアがあります。
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<session JWT>インタラクティブな UI のリモート操作（{ "action": "get_state", "id": "req-1" }）のため。トークンはブラウザのセッション JWT です — API キーはアップグレード前に 401 で拒否されます。データチャネルではありません — すべての読み取り/書き込みは REST を経由します。単一インスタンスのみ。レプリカ間でファンアウトされません。
書き込みエンドポイント（POST、PUT、DELETE）は Idempotency-Key ヘッダーを受け付けます。同じキー + 同じボディはキャッシュされたレスポンスを再生します（24 時間のウィンドウ）。同じキー + 異なる ボディは 409 idempotency_conflict を返します。キーはそれを送信した認証情報にスコープされます。GET/HEAD/OPTIONS、/openapi.json と /docs、/api/auth/*、/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 です。
cursor/limit なしの通常のリストがレスポンスを切り詰めた場合は、ヘッダーでそれを示します — X-Tracker-Pagination-Truncated、X-Tracker-Pagination-Limit、X-Tracker-Pagination-Offset、X-Tracker-Pagination-Next-Offset。次のページを取得するには、最後のものを offset= として渡し返します。総件数のヘッダーはありません。
フィールドの射影
Section titled “フィールドの射影”リスト系エンドポイントは、特定のフィールドのみを返すために fields=（カンマ区切り）を受け付けます。story_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 内、details なし（ほとんどの検証: 空白/長さ/null バイト/メール） |
| 400 | validation_failed | 構造化された入力エラー。details.fields は問題のあるフィールド名の 配列 |
| 401 | unauthenticated | トークンの欠落/無効 |
| 403 | unauthorized_operation | 認証済みだがロールが不十分 |
| 404 | unfound_resource | 見つからない — 非メンバーにも返される |
| 409 | conflict | リソースの競合（例: 重複） |
| 409 | idempotency_conflict | Idempotency-Key が異なるボディで再利用された |
| 409 | stale_write · import_already_running | expected_updated_at 以降にストーリーが変更された · インポートがすでに実行中 |
| 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 | サーバー障害 — 汎用メッセージ。再試行して安全 |
| 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/feedback: 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 が返されます。