Đặc tả API

Tham chiếu endpoint REST đầy đủ. Để có hướng dẫn và ví dụ, xem Hướng dẫn API.

Mọi thứ một thành viên dự án có thể làm trong giao diện web đều có sẵn ở đây — SPA tiêu thụ chính API này. Các thao tác yêu cầu vai trò manager được đánh dấu (manager); mọi thứ khác chỉ cần là thành viên dự án (hoặc, đối với các thao tác đọc được đánh dấu (viewer), bất kỳ cấp quyền truy cập nào). Các bảng dưới đây nêu tên mọi nhóm route mà máy chủ gắn vào; những nhóm được tóm tắt trong một dòng được mô tả đầy đủ trong openapi.json trực tiếp.

Cơ sở (Base)

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 phục vụ API y hệt. Mọi request và response đều là JSON, ngoại trừ một vài endpoint tải lên tệp chấp nhận multipart.

Hai nhóm nằm cao hơn một cấp, dưới /api thay vì /api/v1: bề mặt xác thực (/api/auth/*) và các biểu mẫu công khai (/api/contact, /api/feedback). Các cách viết /api/v1/… của chúng trả về 404.

Xác thực

Mọi request đã xác thực gửi một thông tin xác thực qua một trong các cách:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

User key bắt đầu bằng ea_user_, agent key bằng ea_agent_, và access token MCP bằng ea_mcp_. Xem Hướng dẫn API → Ba loại thông tin xác thực.

Các endpoint không cần xác thực: /openapi.json, /docs, các endpoint /api/auth/*, và các lượt tra cứu dữ liệu tham chiếu (/story_types, /story_states, /effort_scales, /priority_scales). /meta là cần xác thực — bất kỳ key hợp lệ nào cũng dùng được, nhưng nó không có phạm vi theo dự án (một agent key gắn với dự án cũng truy cập được nó).

Vai trò

Bốn cấp độ kiểm soát các endpoint có phạm vi theo dự án:

Cấp độ	Ai vượt qua	Các thao tác điển hình
public viewer	bất kỳ ai, trên một dự án có chế độ hiển thị công khai	đọc board: story, iteration, tìm kiếm, hoạt động của story và epic (với chi tiết tác nhân bị che)
viewer	viewer, member, manager	đọc (liệt kê/lấy story, tìm kiếm, số liệu, danh sách định dạng xuất)
member	member, manager	mọi thao tác ghi với hạng mục công việc (story, task, comment, …), luồng sự kiện
manager	chỉ manager	cài đặt dự án, quản lý thành viên, agent key, xóa, nhập, tải bản xuất, sao lưu, audit log

Agent giữ cùng các vai trò như thành viên — viewer, member, hoặc manager — bị giới hạn ở vai trò của thành viên đã phát hành key. Một người không phải thành viên nhận 404 unfound_resource (không phải 403) trên các path dự án riêng tư, nên các project ID không thể bị liệt kê.

Các endpoint tự mô tả

Phương thức	Path	Mô tả
GET	/openapi.json	Đặc tả OpenAPI 3 trực tiếp, bao gồm cả request body. Không cần xác thực.
GET	/docs	Swagger UI. Không cần xác thực.
GET	/meta	Danh tính người gọi (auth.kind/key_id/agent_id/project_id) + đồ thị chuyển đổi theo loại story. Cần xác thực (bất kỳ key hợp lệ nào; không có phạm vi theo dự án). Gọi cái này trước tiên.
GET	/api/health · /api/config	Kiểm tra hoạt động, và cấu hình công khai của bản triển khai (chế độ một tổ chức, các tính năng tùy chọn đang bật, tên phiên bản). Không cần xác thực, nằm ngoài /v1.

Auth (/api/auth/*, bên ngoài /v1)

Các endpoint phiên, không cần xác thực trừ khi có ghi chú. SPA điều khiển chúng; script thường dùng một API key thay vào đó.

Phương thức	Path	Mô tả
POST	/auth/register	Đăng ký một tài khoản mới — được bảo vệ bằng reCAPTCHA; sau đó tài khoản phải qua thử thách SMS
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Gửi / kiểm tra mã SMS đăng ký (bypass do nhà vận hành kiểm soát)
GET	/auth/config	Những phương thức đăng nhập mà bản triển khai cung cấp
POST	/auth/login	Đăng nhập bằng email + mật khẩu; trả về một JWT phiên, hoặc một thử thách TOTP
POST	/auth/login/totp	Hoàn tất đăng nhập bằng mã từ ứng dụng xác thực hoặc một mã khôi phục
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Đăng nhập WebAuthn không cần mật khẩu
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	Đăng nhập OAuth bằng GitHub hoặc Google
POST	/auth/refresh · /auth/refresh/revoke	Xoay vòng refresh token / thu hồi nó
POST	/auth/logout	Đăng xuất (thu hồi refresh token)
POST	/auth/forgot-password · /auth/reset-password	Yêu cầu email đặt lại / dùng token đặt lại
POST	/auth/accept-invite/lookup · /auth/accept-invite	Phân giải một token lời mời → email / chấp nhận lời mời dự án (sau khi đã xác thực)

Tài khoản / danh tính

Những endpoint này hành động trên người gọi và chỉ cần một key hợp lệ (không cần vai trò dự án).

Phương thức	Path	Mô tả
GET	/me	Hồ sơ người dùng hiện tại
PUT	/me	Cập nhật hồ sơ
DELETE	/me	Xóa tài khoản — bị từ chối khi bạn là owner duy nhất của một tổ chức hoặc của một dự án có thành viên khác
GET	/me/deletion-impact	Việc xóa tài khoản sẽ gỡ bỏ những gì và điều gì đang chặn nó
PUT	/me/password	Đổi mật khẩu
PUT	/me/settings	Cập nhật cài đặt (theme, tùy chọn thông báo)
POST	/me/avatar	Tải lên avatar (multipart)
POST	/me/api-token/regenerate	Xoay vòng API token của bạn — vô hiệu hóa các phiên/key hiện có
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Quản lý các API key người dùng (ea_user_)
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Đăng ký xác thực hai yếu tố (TOTP); verify trả về các mã khôi phục một lần duy nhất
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Đăng ký và gỡ passkey
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Connected apps — các client MCP và ứng dụng OAuth bạn đã cấp quyền
GET	/me/activity	Hoạt động của bạn trên tất cả các dự án
GET	/me/stories	Các story bạn sở hữu, đã yêu cầu, hoặc theo dõi trên mọi dự án mà token truy cập được — role=owned|requested|following, state=, cursor= / limit= (tối đa 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Hộp thư @-nhắc đến (unacked=true để lọc) và xác nhận đã đọc — cũng được gộp vào luồng thông báo bên dưới
GET	/me/data-export	Tự xuất dữ liệu của bạn theo GDPR
GET	/me/consent · POST /me/consent	Đọc / ghi nhận sự đồng ý ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Các tài liệu clickwrap đang chờ / ghi nhận sự chấp nhận
GET / PUT	/agent/me	Danh tính và hồ sơ của chính một agent key, agent có thể đọc và sửa (phần tương ứng phía agent của /me)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	Liên hệ + phản hồi trong ứng dụng. Nằm ngoài /v1; giới hạn tốc độ theo IP

Dữ liệu tham chiếu (không cần xác thực)

Các lượt tra cứu dữ liệu mầm (seed) được dùng khi tạo/ước lượng story. ID ổn định.

Phương thức	Path	Mô tả
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	các thang ước lượng khả dụng
GET	/effort_scales/{scale_id}/values	các giá trị điểm trong một thang đo
GET	/priority_scales · /priority_scales/{scale_id}/values	các thang độ ưu tiên và giá trị của chúng (priority_id trên một story được phân giải tại đây)

Tổ chức

Chỉ dành cho dịch vụ được lưu trữ — một bản cài đặt tự lưu trữ chạy ở chế độ một tổ chức và không gắn các endpoint này (ngoại trừ danh sách tổ chức). Vai trò là vai trò tổ chức: owner, admin, member.

Phương thức	Path	Mô tả
GET / POST	/organizations	Liệt kê các tổ chức của bạn / tạo một tổ chức
GET / PUT / DELETE	/organizations/{oid}	Đọc, đổi tên (tên + slug; owner hoặc admin), xóa
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Thành viên và lời mời; lời mời mang một trần vai trò (không bao giờ cao hơn vai trò người gọi; owner không bao giờ được mời)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Đổi vai trò hoặc xóa tối đa 200 thành viên cùng lúc. Tất cả hoặc không: một lô sẽ xóa owner cuối cùng hoặc để một dự án không có chủ sở hữu sẽ bị từ chối toàn bộ; với reassign_confirmed, bạn trở thành chủ sở hữu các dự án đó
DELETE	/organizations/{oid}/invitations/{invitation_id}	Thu hồi một lời mời đang chờ
POST	/organizations/{oid}/transfer-ownership	Chuyển vai trò owner cho một thành viên khác
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Che tên / email / avatar của một thành viên trên toàn tổ chức
GET	/organization-invitations/{token} · POST …/{token}/accept	Phân giải / chấp nhận một lời mời tổ chức gửi qua email
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Xuất tổ chức, chỉ owner: một zip gồm bản dump SQL và mọi tệp đính kèm, chạy dưới dạng job

Dự án

Phương thức	Path	Mô tả
GET	/projects	Liệt kê các dự án của bạn (limit ≤ 200)
POST	/projects	Tạo một dự án
GET	/projects/{id}	Lấy chi tiết dự án (viewer)
PUT	/projects/{id}	Cập nhật cài đặt dự án (manager)
DELETE	/projects/{id}	Xóa một dự án (manager)
POST	/projects/{id}/pin	Ghim / bỏ ghim dự án trên danh sách dự án của bạn
POST	/projects/{id}/transfer-organization	Chuyển dự án sang một tổ chức khác (manager)
POST	/projects/{id}/slack/test	Gửi một tin nhắn thử đến luồng Slack của dự án (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Các dự án trưng bày công khai: kiểm tra xem bạn có thể nhận một dự án không, nhận nó, khởi tạo dữ liệu cho nó
GET	/projects/{id}/audit-log	Đọc audit log — lịch sử dự án cùng hoạt động theo từng story / từng epic qua surface=; quyền truy cập khác nhau theo surface, xem bên dưới
GET	/projects/{id}/events	Luồng sự kiện phân trang theo cursor (member) — xem Events

Tham số query của audit log: event_type= (một loại hoặc danh sách phân tách bằng dấu phẩy), limit= (≤ 1000), before= (con trỏ keyset, created_at dạng ISO-8601), surface= (project_history, story_activities, epic_activities), target_id= (id của story/epic — bắt buộc khi surface=story_activities hoặc epic_activities). Quyền truy cập: log không lọc và surface=project_history là (manager); story_activities / epic_activities mọi thành viên dự án đều đọc được, và đọc ẩn danh được trên dự án công khai với PII của tác nhân bị che.

Thành viên, agent, và agent key

Phương thức	Path	Mô tả
GET	/projects/{id}/memberships	Liệt kê thành viên (viewer)
POST	/projects/{id}/memberships	Mời một thành viên bằng email (manager)
PUT	/projects/{id}/memberships/{mid}	Cập nhật vai trò (manager)
DELETE	/projects/{id}/memberships/{mid}	Loại bỏ một thành viên (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Các thành viên tổ chức chưa có trong dự án / thêm một người mà không cần lời mời qua email (manager)
POST	/projects/{id}/members/join	Một owner hoặc admin của tổ chức tham gia một dự án trong tổ chức của mình với vai trò manager, hoặc tự thăng cấp lên manager (hành động Make me owner trên danh sách dự án)
PUT	/projects/{id}/members/{mid}/anonymization	Che tên / email / avatar của một thành viên trên dự án này (manager)
GET / POST	/projects/{id}/agent_keys	Liệt kê / phát hành agent key — manager, hoặc các vai trò mà chính sách creator-roles của dự án cho phép
DELETE	/projects/{id}/agent_keys/{kid}	Thu hồi một agent key
GET	/projects/{id}/agent_keys/onboarding	Gói onboarding: các prompt và tệp cấu hình cho các client agent phổ biến
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Các agent của dự án và hồ sơ của chúng (tên, chữ viết tắt, mô tả, màu)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Xoay vòng key của một agent (giữ nguyên danh tính và lịch sử) / tải lên avatar của nó

Story

Mọi thao tác ghi story cần vai trò member.

Phương thức	Path	Mô tả
GET	/projects/{id}/stories	Liệt kê story (phân trang, lọc được) (viewer)
POST	/projects/{id}/stories	Tạo một story
GET	/projects/{id}/stories/{sid}	Lấy một story (viewer)
PUT	/projects/{id}/stories/{sid}	Cập nhật một story
DELETE	/projects/{id}/stories/{sid}	Xóa một story
POST	/projects/{id}/stories/{sid}/transitions	Thay đổi trạng thái có xác thực
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	Từ chối một story đã giao / đưa một story bị từ chối trở lại started (rejected là trạng thái cuối đối với /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Lưu trữ / bỏ lưu trữ một story
POST	/projects/{id}/stories/bulk_transition	Chuyển đổi nhiều story (1–100) cùng lúc
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Lưu trữ, xóa, nhân bản, hoặc di chuyển (đến một bảng / vị trí) nhiều story
POST	/projects/{id}/stories/{sid}/duplicate	Nhân bản một story
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Tư cách thành viên epic của story
GET	/short-links/{code} · /story-references	Phân giải một liên kết rút gọn /s/<code> thành story của nó / phân giải tối đa 100 tham chiếu story (#id, URL) thành các story mà người gọi có thể đọc

Tham số truy vấn danh sách story: archived= (exclude mặc định / include / only — bộ lọc lưu trữ ba trạng thái; thay thế include_archived=true đã lỗi thời, nay là bí danh của archived=include), include_done=true (cho phép các story ở bảng Done bị đóng băng trên các iteration đã qua, mặc định bị loại trừ). Phân trang (cursor= / limit= / offset=) và tập trường rút gọn (fields=) tuân theo Phân trang và Phép chiếu trường.

Create (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate là nhãn của giá trị trên thang đo, dưới dạng chuỗi ("3", "13"); một số JSON sẽ bị từ chối. labels chấp nhận ["auth"] hoặc [{ "name": "auth" }]; các nhãn chưa biết sẽ được tạo. Giá trị mặc định: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): cùng các trường, tất cả đều tùy chọn, cộng thêm "position" (float), "force_state_change" (bool), và "expected_updated_at" (RFC 3339 — việc lưu mô tả bị từ chối với 409 stale_write nếu story đã thay đổi kể từ lúc bạn đọc nó). Các thao tác ghi story cũng tôn trọng If-Match so với ETag của story; không khớp sẽ là 412 precondition_failed.

Transition (POST …/transitions): { "to": "<state>" }. Trường là to. Trả về { story_id, state }. Bước di chuyển không hợp lệ → 422 invalid_transition với details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. Mỗi story được đánh giá độc lập; trả về { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Tài nguyên con của story

Tất cả đều là member. Thao tác List/GET trên hầu hết là (viewer).

Phương thức	Path	Body / ghi chú
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) } hoặc { comment_emoji }. GET nhận fields= (danh sách cho phép: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) cùng với 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; các URL GitHub /pull/ và /tree/ được tự động gán loại
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Tạo: { reviewer_id? / reviewer_agent_id?, comment? } — bỏ qua cả hai để tự gán cho mình. Cập nhật: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — bỏ qua cả hai để thêm người gọi
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}	tải lên multipart — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, hình ảnh / CSV / văn bản ≤ 10 MB; thao tác list là (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Tệp đính kèm dạng liên kết — một URL bên ngoài được giữ cùng với các tệp đính kèm thay vì là một liên kết mã
GET	/attachments/{token} · /api/avatars/{token}	Đọc một tệp đính kèm hoặc một avatar theo token — các URL mà API trả ra; không cần X-TrackerToken

Epic

Cùng cấu trúc như story, trừ máy trạng thái. member cho thao tác ghi, (viewer) cho thao tác đọc.

Phương thức	Path	Mô tả
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epic mang một tên, một mô tả Markdown, và một nhãn nền kết nối các story của nó
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Bình luận trên epic
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ các biến thể /agents/{aid})	Owner và follower, thành viên hoặc agent — owner của một epic được lan truyền xuống các story của nó
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Tệp đính kèm, cùng giới hạn như story
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Tiến độ theo từng epic: burnup, năng suất, sức khỏe, dự báo (viewer)

Nhãn (Label)

member cho thao tác ghi, (viewer) cho thao tác đọc.

Phương thức	Path	Mô tả
GET / POST	/projects/{id}/labels	Liệt kê / tạo một nhãn
PUT / DELETE	/projects/{id}/labels/{lid}	Cập nhật / xóa một nhãn
POST	/projects/{id}/labels/{lid}/archive	Lưu trữ (ẩn mềm) một nhãn

Iteration

Thao tác đọc mở cho mọi vai trò dự án, và cho người ẩn danh trên một dự án công khai.

Phương thức	Path	Mô tả
GET	/projects/{id}/iterations	Liệt kê iteration (≤ 500 mỗi trang; mang một ETag và các header tiếp nối X-Tracker-Pagination-* khi bị cắt bớt)
GET	/projects/{id}/iterations/{itid}	Một iteration
GET	/projects/{id}/iterations/first-preview	Các ngày mà iteration đầu tiên sẽ nhận, được hiển thị trong bước xác nhận khởi tạo
POST	/projects/{id}/iterations	Tạo một iteration thủ công (member)
DELETE	/projects/{id}/iterations/{itid}	Xóa một iteration (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Ghi đè velocity của một iteration mà không thay đổi chiến lược của dự án (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Các story đã được chấp nhận của một iteration đã đóng, có phân trang

Tìm kiếm, số liệu, tùy chọn

Phương thức	Path	Mô tả
GET	/projects/{id}/search?q=…	Tìm kiếm mạnh mẽ — toàn văn + các qualifier facet / khoảng ngày / người (DSL kiểu GitHub); trả về { results, total, limit, offset }. query là bí danh của q; limit= (mặc định 50, tối đa 1000) / offset= để phân trang; sort= sắp xếp theo relevance (mặc định), created, created_asc, state, hoặc updated. (viewer) — xem Hướng dẫn
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Các chuỗi dữ liệu của trang Metrics (viewer); số liệu epic nằm dưới /analytics/epics ở trên
GET	/projects/{id}/backlog/grouping	Các nhóm iteration được dự báo của Backlog (viewer)
GET / PUT	/projects/{id}/preferences	Tùy chọn board của bạn cho dự án này — mọi vai trò dự án, chỉ hàng dữ liệu của chính bạn

Events

Phương thức	Path	Mô tả
GET	/projects/{id}/events	Luồng sự kiện phân trang theo cursor (member) — viewer nhận 403

Các tham số truy vấn: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. Phản hồi bao gồm next_cursor. Truyền event_id cuối cùng bạn đã thấy làm since để tiếp tục.

Thông báo

Luồng thông báo hợp nhất trong ứng dụng: các dòng thông báo hạng nhất (yêu cầu review, hoạt động của story, lời mời, …) được gộp với hộp thư @-nhắc đến thành một luồng duy nhất, mới nhất trước. Id trong luồng mang tiền tố nguồn (nt-… / sc-… / ec-…). Phiên thành viên và khóa ea_user_* đọc các dòng phía thành viên; khóa ea_agent_* đọc các dòng phía agent.

Phương thức	Path	Mô tả
GET	/me/notifications	Luồng thông báo của bạn. Bộ lọc: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); phân trang bằng cursor= / limit=
GET	/me/notifications/unread-count	Tổng chưa đọc — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Đánh dấu tất cả là đã đọc; trả về bộ đếm mới
POST	/me/notifications/{id}/ack	Đánh dấu một mục là đã đọc (idempotent)
POST	/me/notifications/{id}/accept	Chấp nhận lời mời vào dự án / tổ chức ngay từ luồng (chỉ token thành viên)
POST	/me/notifications/{id}/decline	Từ chối lời mời vào dự án / tổ chức (chỉ token thành viên)
GET	/me/notifications/resolve-invite?token=…	Đối chiếu token lời mời gửi qua email với id thông báo của bạn — { "id": "nt-…" } hoặc { "id": null }
GET	/me/notifications/stream	Push trực tiếp — Server-Sent Events (text/event-stream); xem bên dưới

Endpoint stream không phải endpoint JSON nên không có trong đặc tả OpenAPI: nó giữ kết nối mở và phát một frame không có payload ({"type":"notification","kind":…}) mỗi khi có nội dung mới, báo cho client tải lại luồng. Kết nối bị ngắt phía máy chủ sau 45 phút — hãy kết nối lại và xác thực lại. Chỉ dành cho phiên thành viên và khóa ea_user_*; khóa ea_agent_* nhận 403.

Nhập (Import) (manager)

Phương thức	Path	Mô tả
POST	/projects/{id}/import	Các nguồn từ tệp: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Đồng bộ — trả lời bằng các bộ đếm kết quả.
POST	/projects/{id}/import/json	Thân JSON; source=github không cần tệp — owner, repo, token tùy chọn, và các cờ opt-in include_pull_requests / include_milestones / include_releases / include_dependencies; các nguồn từ tệp gửi file_base64. Bất đồng bộ: trả về 202 { import_id, status }. Máy chủ lấy dữ liệu qua API GraphQL của GitHub, vốn từ chối lời gọi ẩn danh, nên luôn có một token đến được GitHub — token của bạn, hoặc token dùng chung của bản triển khai. Xem Hướng dẫn.
GET	/projects/{id}/imports/{import_id}	Poll một job: status chạy theo pending → fetching → writing → done | failed, với progress_current / progress_total trong lúc lấy dữ liệu và các bộ đếm kết quả khi done

Mỗi dự án chỉ chạy một lần nhập tại một thời điểm; một POST thứ hai trong khi một lần nhập đang chạy sẽ nhận 409 import_already_running. dry_run: true (trong thân JSON hoặc dry_run=true multipart) xem trước bất kỳ nguồn nào: phân tích, đối chiếu, khử trùng lặp, trả về cùng các bộ đếm { imported, skipped, errors, unmatched }, rồi hoàn tác — không có gì được ghi. Giới hạn: thân 10 MiB và 5.000 story mỗi lần nhập với các nguồn theo tệp (vượt một trong hai → 400, không ghi gì). Nguồn GitHub không có trần — nó ghi theo từng khối thay vì một giao dịch duy nhất. Nhập lại là idempotent theo id nguồn — các hàng đã được nhập bị bỏ qua, không nhân đôi.

Xuất (Export)

Phương thức	Path	Mô tả
GET	/projects/{id}/export/formats	Các định dạng đã đăng ký: { id, name, content_type, drops, includes_archived }. Mọi vai trò dự án.
GET	/projects/{id}/export/{format}	Tải xuống một định dạng (manager). Trao đổi: eat (đầy đủ độ trung thực), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; tài liệu: pdf, docx.
GET	/projects/{id}/export/attachments	Mọi tệp đính kèm dưới dạng một zip có thể duyệt (tệp giữ tên gốc; manifest JSON + CSV) (manager).

Xuất tài liệu (pdf, docx) nhận thêm các tham số truy vấn: page_size= (letter mặc định / a4 / legal / folio), from= / to= (giới hạn cửa sổ story — RFC 3339 hoặc chỉ YYYY-MM-DD; một story nằm trong khoảng khi created hoặc completed_at của nó rơi vào đó), include_icebox= / include_backlog= (cả hai mặc định là false, nên bản xuất để chia sẻ chỉ hiển thị công việc đã lên lịch / đang thực hiện). Các định dạng CSV trao đổi bỏ qua chúng.

Sao lưu và khôi phục (manager)

Phương thức	Path	Mô tả
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Liệt kê các snapshot, chụp một snapshot ngay, đọc một snapshot, và bản tóm tắt sức khỏe lưu giữ
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Khôi phục toàn bộ một snapshot, hoặc các bảng được chọn từ đó, và poll quá trình khôi phục

Các POST nằm ở bậc giới hạn tốc độ sensitive (bên dưới).

MCP và nhà cung cấp OAuth

East Agile Tracker là một nhà cung cấp OAuth 2.1 cho các client MCP. Một client khám phá nó tại /.well-known/oauth-authorization-server và /.well-known/oauth-protected-resource/mcp, đưa bạn đến /oauth/authorize (trang đồng ý), đổi mã tại /oauth/token, rồi giao tiếp MCP tại /mcp bằng token ea_mcp_* nhận được. Các quyền cấp được liệt kê và thu hồi tại /me/oauth_grants. Các endpoint của nhà cung cấp có bậc giới hạn tốc độ riêng.

WebSocket

wss://eastagiletracker.com/ws/control?token=<session JWT>

Dành cho điều khiển từ xa giao diện một cách tương tác ({ "action": "get_state", "id": "req-1" }). Token là một JWT phiên trình duyệt — một API key bị từ chối với 401 trước khi nâng cấp kết nối. Không phải một kênh dữ liệu — mọi thao tác đọc/ghi đều đi qua REST. Chỉ một phiên bản (single-instance); không được phân phối (fan-out) qua các bản sao.

Idempotency

Các endpoint ghi (POST, PUT, DELETE) chấp nhận một header Idempotency-Key. Cùng key + cùng body sẽ phát lại phản hồi được lưu cache (cửa sổ 24 giờ); cùng key + một body khác sẽ trả về 409 idempotency_conflict. Key có phạm vi theo thông tin xác thực đã gửi nó. Không áp dụng cho GET/HEAD/OPTIONS, /openapi.json và /docs, /api/auth/*, hoặc các bản tải lên multipart trên các path /attachments. Các phản hồi dừng lại trước khi có câu trả lời nghiệp vụ không bao giờ được cache — 401, 403, 404, 429, và mọi 5xx — nên một lần thử lại sau bất kỳ phản hồi nào trong số đó sẽ đến được handler; 400, 409, 412, và 422 là câu trả lời của nghiệp vụ và được phát lại như một thành công.

Phân trang

Các endpoint danh sách chấp nhận cursor=<opaque> và limit=<n>. Khi được đặt, phản hồi là { "items": [...], "next_cursor": "<str|null>" }; truyền next_cursor trở lại để sang trang. Trần của limit tùy theo endpoint: 200 cho story, bình luận, và dự án; 500 cho sự kiện; 1000 cho tìm kiếm và audit log.

Một danh sách thường (không có cursor/limit) phải cắt bớt phản hồi sẽ báo điều đó qua các header — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, và X-Tracker-Pagination-Next-Offset; truyền giá trị cuối cùng trở lại làm offset= cho trang tiếp theo. Không có header tổng số đếm.

Phép chiếu trường (Field projection)

Các endpoint danh sách chấp nhận fields= (cách nhau bằng dấu phẩy) để chỉ trả về các trường cụ thể. story_id luôn được bao gồm; một tên trường chưa biết sẽ trả về 400 validation_failed với các tên vi phạm trong details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Định dạng lỗi

Mọi lỗi JSON đều có code và error; một số thêm details:

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

Trạng thái	code	Khi nào
400	invalid_parameter	đầu vào sai; thông điệp trong error, không có details (hầu hết kiểm tra: trống/độ dài/null-byte/email)
400	validation_failed	lỗi đầu vào có cấu trúc; details.fields là một mảng tên các trường vi phạm
401	unauthenticated	thiếu/token không hợp lệ
403	unauthorized_operation	đã xác thực nhưng vai trò không đủ
404	unfound_resource	không tìm thấy — cũng được trả về cho người không phải thành viên
409	conflict	xung đột tài nguyên (ví dụ trùng lặp)
409	idempotency_conflict	Idempotency-Key được dùng lại với một body khác
409	stale_write · import_already_running	story đã thay đổi kể từ expected_updated_at của bạn · một lần nhập đang chạy
412	precondition_failed	If-Match không khớp với ETag hiện tại của tài nguyên; details mang expected và current
413	request_too_large	body vượt quá giới hạn kích thước của route
422	invalid_transition	bước di chuyển trạng thái không hợp lệ; details mang { from, to, allowed }
429	rate_limited	quá nhiều request từ IP này trên một route có giới hạn tốc độ; header Retry-After
500	internal_error	lỗi máy chủ — thông điệp chung; an toàn để thử lại
503	not_configured	bản triển khai thiếu tích hợp mà route này cần (SMS, lưu trữ đối tượng, …)

details.fields là một mảng JSON tên các trường (ví dụ ["to"]), đôi khi kèm các khóa bổ sung như max. Không có ánh xạ trường→thông điệp.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Giới hạn tốc độ (Rate limit)

Theo IP của client, trên một số ít route; lưu lượng API đã xác thực ở những nơi khác không bị giới hạn tốc độ. Giá trị mặc định (mỗi cặp là tốc độ duy trì và burst, nhà vận hành có thể điều chỉnh):

• Auth — /api/auth/*: 0.5 req/s, burst 20.
• OAuth provider — /oauth/*: 1 req/s, burst 60.
• Public — /api/contact: 0.2 req/s, burst 10.
• Feedback — /api/feedback: ba bậc chồng lên nhau — một lần gửi mỗi 15 giây, 10 lần mỗi giờ, 36 lần mỗi ngày.
• Avatars — chuyển hướng avatar không cần xác thực: 20 req/s, burst 200.
• Sensitive — các POST sao lưu và khôi phục: ~0.002 req/s, burst 5.

Một giới hạn bị vượt quá sẽ trả về 429 với một header Retry-After và phong bì lỗi JSON tiêu chuẩn, code: "rate_limited".