完全な REST エンドポイントリファレンスです。チュートリアルと例については API ガイド を参照してください。
プロジェクトの member が Web UI でできることはすべてここで利用できます — SPA はこの同じ API を消費しています。owner ロールを必要とする操作は (owner) とマークされています。それ以外はプロジェクトメンバーシップのみ（または、(viewer) とマークされた読み取りについては任意のアクセスレベル）を必要とします。
https://eastagiletracker.com/api/v1https://api.eastagiletracker.com/api/v1 は同一の API を提供します。すべてのリクエストとレスポンスは JSON です。ただし、multipart を受け付けるいくつかのファイルアップロードエンドポイントを除きます。
すべての認証済みリクエストは、次のいずれかで API キーを送ります。
X-TrackerToken: <key>Authorization: Bearer <key>
ユーザーキーは ea_user_ で始まります。エージェントキーは ea_agent_ で始まります。API ガイド → 2 種類のキー を参照してください。
認証不要のエンドポイント: /openapi.json、/docs、/auth/* エンドポイント、参照データのルックアップ（/story_types、/story_states、/effort_scales、…）。/meta は 認証済み です — 任意の有効なキーが機能しますが、プロジェクトスコープではありません（プロジェクトにバインドされたエージェントキーでも到達できます）。
3 つのレベルがプロジェクトスコープのエンドポイントを制御します。
| レベル | 通過する者 | 典型的な操作 |
|---|---|---|
| viewer | viewer, member, owner | 読み取り（ストーリーの一覧/取得、検索、分析） |
| member | member, owner | すべての作業項目の書き込み（ストーリー、タスク、コメント、…） |
| owner | owner のみ | プロジェクト設定、メンバーシップ管理、エージェントキー、削除、インポート、監査ログ |
非メンバーはプロジェクトパスで 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）+ ストーリータイプの遷移グラフ。認証済み（任意の有効なキー。プロジェクトスコープではない）。最初にこれを呼びます。 |
アカウント / アイデンティティ
Section titled “アカウント / アイデンティティ”これらは呼び出し元に作用し、有効なキーのみを必要とします（プロジェクトロールは不要）。
| Method | Path | 説明 |
|---|---|---|
| POST | /auth/register | 新規アカウントを登録 |
| POST | /auth/login | サインインし、セッショントークンを返す |
| POST | /auth/logout | サインアウト |
| POST | /auth/forgot-password | パスワードリセットメールを要求 |
| POST | /auth/reset-password | リセットトークンを使って新しいパスワードを設定 |
| GET | /auth/verify-email | メールアドレスを確認 |
| POST | /auth/accept-invite/lookup | 招待トークンを解決 → メールアドレス（認証不要） |
| POST | /auth/accept-invite | プロジェクトの招待を受け入れる（認証後） |
| GET | /me | 現在のユーザープロフィール |
| PUT | /me | プロフィールを更新 |
| DELETE | /me | アカウントを削除 |
| 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/activity | 全プロジェクトにわたるあなたのアクティビティ |
| GET | /me/data-export | あなたのデータの GDPR セルフエクスポート |
| GET | /me/consent · POST /me/consent | 同意を読み取り / 記録（{ consent_type, granted }） |
| GET | /legal/pending · POST /legal/accept | 保留中のクリックラップ文書 / 受け入れを記録 |
| POST | /contact · POST /feedback · POST /feedback/with-screenshot | お問い合わせ + アプリ内フィードバック |
参照データ（認証不要）
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 | スケール内のポイント値 |
プロジェクト
Section titled “プロジェクト”| Method | Path | 説明 |
|---|---|---|
| GET | /projects | あなたのプロジェクトを一覧表示 |
| POST | /projects | プロジェクトを作成 |
| GET | /projects/{id} | プロジェクト詳細を取得 (viewer) |
| PUT | /projects/{id} | プロジェクト設定を更新 (owner) |
| DELETE | /projects/{id} | プロジェクトを削除 (owner) |
| GET | /projects/{id}/audit-log | プロジェクトのアクティビティストリーム (owner) |
| GET | /projects/{id}/events | カーソルでページ分割されたイベントストリーム (viewer) — イベント を参照 |
メンバーとエージェントキー
Section titled “メンバーとエージェントキー”| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/memberships | メンバーを一覧表示 (viewer) |
| POST | /projects/{id}/memberships | メンバーをメールで招待 (owner) |
| PUT | /projects/{id}/memberships/{mid} | ロールを更新 (owner) |
| DELETE | /projects/{id}/memberships/{mid} | メンバーを削除 (owner) |
| GET / POST | /projects/{id}/agent_keys | エージェントキーを一覧 / 発行 (owner) |
| DELETE | /projects/{id}/agent_keys/{kid} | エージェントキーを取り消す (owner) |
すべてのストーリー書き込みは 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/bulk_transition | 多くのストーリー（1〜100）を一度に遷移 |
| POST | /projects/{id}/stories/bulk-delete | 多くのストーリーを削除 |
| POST | /projects/{id}/stories/bulk-duplicate | 多くのストーリーを複製 |
| POST | /projects/{id}/stories/{sid}/duplicate | 1 つのストーリーを複製 |
作成（POST …/stories）: { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }。labels は ["auth"] または [{ "name": "auth" }] を受け付けます。未知のラベルは作成されます。デフォルト: story_type=feature、current_state=unstarted。
更新（PUT …/stories/{sid}）: 同じフィールド、すべて任意、加えて "position"（float）と "force_state_change"（bool）。
遷移（POST …/transitions）: { "to": "<state>", "reason"? }。フィールドは to です。{ story_id, state } を返します。不正な移動 → details: { from, to, allowed } 付きの 422 invalid_transition。
一括遷移（POST …/bulk_transition）: { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }。各ストーリーは独立して判断されます。{ 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 / POST | /projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid} | { blocker_desc, resolved? } |
| GET / POST | /projects/{id}/stories/{sid}/links · DELETE …/links/{lid} | { url, link_type?, title? } |
| GET / POST | /projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid} | { reviewer_id? / reviewer_agent_id?, 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 アップロード（各 ≤ 2 GB）。一覧は (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 | イテレーションを一覧表示 (member) |
| POST | /projects/{id}/iterations | 手動イテレーションを作成 (owner) |
| DELETE | /projects/{id}/iterations/{itid} | イテレーションを削除 (owner) |
検索、分析、メトリクス、設定
Section titled “検索、分析、メトリクス、設定”| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/search?query=… | フィルター構文検索 (viewer) — ガイドを参照 |
| GET | /projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections} | 分析 (viewer)。イテレーションのドリルダウンは ?iteration_id= を取る |
| GET | /projects/{id}/metrics/{velocity,burndown,story-types} | メトリクス (viewer) |
| GET / PUT | /projects/{id}/preferences | このプロジェクトに対するあなたのボード設定 (member) |
| Method | Path | 説明 |
|---|---|---|
| GET | /projects/{id}/events | カーソルでページ分割されたイベントストリーム (viewer) |
クエリパラメータ: since=<event_id>、types=story.created,story.transitioned,comment.created,…、limit=、cursor=。レスポンスには next_cursor が含まれます。最後に見た event_id を since として渡すと再開します。
インポート (owner)
Section titled “インポート (owner)”| Method | Path | 説明 |
|---|---|---|
| POST | /projects/{id}/import (+ /json) | Multipart アップロード。source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json。 |
WebSocket
Section titled “WebSocket”wss://eastagiletracker.com/ws/control?token=<key>インタラクティブな UI のリモート操作（{ "action": "get_state", "id": "req-1" }）のため。データチャネルではありません — すべての読み取り/書き込みは REST を経由します。単一インスタンスのみ。レプリカ間でファンアウトされません。
書き込みエンドポイント（POST、PUT、DELETE）は Idempotency-Key ヘッダーを受け付けます。同じキー + 同じボディはキャッシュされたレスポンスを再生します（24 時間のウィンドウ）。同じキー + 異なる ボディは 409 idempotency_conflict を返します。GET/HEAD/OPTIONS、/auth/*、/attachments パスには適用されません。5xx レスポンスは決してキャッシュされません — 再試行はハンドラーに到達します。
ページネーション
Section titled “ページネーション”リスト系エンドポイントは cursor=<opaque> と limit=<n≤200> を受け付けます。設定された場合、レスポンスは { "items": [...], "next_cursor": "<str|null>" } です。next_cursor を渡し返してページングします。一部のリストは X-Tracker-Pagination-Total ヘッダーも返します。
フィールドの射影
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 が異なるボディで再利用された |
| 422 | invalid_transition | 不正な状態移動。details が { from, to, allowed } を運ぶ |
| 500 | internal_error | サーバー障害 — 汎用メッセージ。再試行して安全 |
details.fields はフィールド名の JSON 配列（例: ["to"]）で、max のような追加のキーを伴うこともあります。フィールド→メッセージのマップはありません。
{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }キーごと（認証不要のエンドポイントは IP ごと）、GCRA トークンバケット:
- Auth —
/auth/*: 0.5 req/s、バースト 20。 - Public —
/contact,/feedback: 0.2 req/s、バースト 10。 - Sensitive — パスワードリセット: 約 0.002 req/s、バースト 5。
制限を超えると、Retry-After ヘッダーと プレーンテキスト のボディ（JSON エラーエンベロープではない）を伴う 429 Too Many Requests が返されます。