Hướng dẫn API

API của East Agile Tracker được thiết kế cho agent ngang bằng với cho con người. Mọi thứ bạn có thể làm trong giao diện, bạn đều có thể làm qua API — và một vài thứ mà giao diện không phơi bày cũng có ở đó.

Hướng dẫn này đưa bạn từ con số không đến “viết script cho backlog của bạn” trong chưa đầy mười phút. Để có tham chiếu endpoint đầy đủ, xem Đặc tả API.

Hai loại key

Bạn xác thực bằng một API key trong header X-TrackerToken. Có hai loại:

• User key (ea_user_…) — Hành động với tư cách bạn. Tạo chúng trong Account Settings → API Keys. Dùng những key này cho các script cá nhân, công cụ CLI, tích hợp.
• Agent key (ea_agent_…) — Hành động với tư cách một agent có tên trong một dự án. Tạo chúng với tư cách owner của dự án trong Project Settings → Agents. Dùng những key này cho các AI agent — Claude Code, Codex, của riêng bạn — vốn nên tham gia vào dự án như những đồng đội có tên.

Sự khác biệt:

	User key	Agent key
Phạm vi	Tất cả các dự án của bạn	Một dự án cụ thể
Danh tính trong audit log	Tên của bạn	Tên của agent
Vai trò	Vai trò của bạn trong mỗi dự án	Được đặt khi tạo key (viewer hoặc member)
Thu hồi	Thu hồi một key; bạn vẫn giữ quyền truy cập qua các key/phiên khác	Thu hồi một key; agent mất quyền truy cập ngay lập tức
Phù hợp nhất cho	Tự động hóa cá nhân, script	Các AI agent cần được phân biệt với bạn trong lịch sử

Authorization: Bearer … cũng hoạt động nếu bạn thích kiểu header đó hơn.

Chào, API

Lấy các dự án của bạn:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Hoặc với một agent key, liệt kê dự án mà nó được giới hạn phạm vi vào:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API là JSON, kiểu REST, được phiên bản hóa tại /api/v1/. Cùng cấu trúc cho con người và agent.

Tạo một dự án

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
  }'

Phản hồi bao gồm project_id và bất kỳ giá trị mặc định nào mà máy chủ đã áp dụng (thang ước lượng, done state, v.v.).

Tạo một story

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"]
  }'

Di chuyển một story qua vòng đời

Endpoint chuyển đổi xác thực bước di chuyển được yêu cầu và trả về các trạng thái tiếp theo được phép khi xảy ra lỗi:

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" }'

Trường là to (không phải to_state). Nếu bước di chuyển không hợp lệ — chẳng hạn bạn cố nhảy từ unstarted thẳng đến accepted — phản hồi là 422 invalid_transition với chi tiết lỗi có cấu trúc:

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

Đây là một trong những điều nhỏ khiến API thân thiện với agent: một agent có thể đọc details.allowed và chọn bước di chuyển tiếp theo đúng đắn mà không cần phải trích xuất từ văn xuôi.

Bình luận trên một story

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." }'

Bình luận được quy cho bất kỳ ai sở hữu API key — nếu là một agent key, tác giả của bình luận là agent.

Ghi bất biến (Idempotent)

Mọi endpoint ghi đều chấp nhận một header Idempotency-Key. Thử lại cùng một key với cùng một body, nhận lại cùng một phản hồi. Thử lại cùng một key với một body khác, nhận một 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" }'

Điều này rất quan trọng đối với các agent trong vòng lặp thử lại — gặp sự cố giữa chừng một thao tác ghi, thử lại với cùng key, không có story trùng lặp.

Chuyển đổi hàng loạt

Di chuyển nhiều story cùng lúc. Mỗi story được đánh giá độc lập; một bước di chuyển không hợp lệ không làm hỏng các bước còn lại.

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"
  }'

Theo dõi luồng sự kiện

Đối với các agent muốn phản ứng với những gì con người làm, hãy poll endpoint events:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Phản hồi là một luồng sự kiện được phân trang theo cursor với tác nhân, tài nguyên, và sự thay đổi. Mỗi sự kiện có một ID; truyền ID cuối cùng bạn đã thấy làm since để tiếp tục từ nơi bạn dừng lại. Không webhook, không trích xuất, không bỏ lỡ sự kiện.

Tìm kiếm với cú pháp lọc

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Các bộ lọc khả dụng:

Bộ lọc	Ví dụ	Mô tả
type:	type:feature	Lọc theo loại story
state:	state:started	Lọc theo trạng thái
label:	label:"my label"	Lọc theo nhãn
owner:	owner:claire	Lọc theo owner
requester:	requester:tomas	Lọc theo requestor
has:	has:blocker	Các story có blocker
is:	is:unestimated	Các feature chưa ước lượng

Văn bản tự do khớp với tiêu đề và mô tả. Kết hợp các bộ lọc bằng cách cách chúng bằng khoảng trắng — chúng được AND lại với nhau.

Khám phá API

Đặc tả OpenAPI 3 trực tiếp nằm tại:

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

Swagger UI nằm tại:

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

/openapi.json và /docs không cần xác thực — một agent có thể đọc hợp đồng trước khi nó có key. Khi đã giữ một key, /api/v1/meta (vốn yêu cầu một key hợp lệ) trả về danh tính của nó và đồ thị chuyển đổi theo từng loại story; các lượt tra cứu dữ liệu tham chiếu (/story_types, /story_states, /effort_scales) cũng không cần xác thực. Cùng nhau, chúng cho phép agent trả lời “tôi có thể làm gì ở đây?” mà không cần thử-và-sai với các lỗi 403.

Lưu ý: file openapi.json được phục vụ liệt kê các path nhưng hiện đi kèm các request body trống — hãy dùng cấu trúc trường trong Đặc tả cho các thao tác ghi.

Điều khiển WebSocket

Đối với tự động hóa tương tác — điều khiển một phiên trình duyệt đã đăng nhập từ một script, hoặc điều khiển từ xa giao diện cho các bài hướng dẫn — có một kênh WebSocket:

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

Hầu hết người dùng không bao giờ cần đến nó; nó ở đó cho các trường hợp mà REST chưa đủ.

Nhập từ một tracker khác

Nếu bạn đang viết script cho một cuộc di chuyển hàng loạt:

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"

Các nguồn được hỗ trợ: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Định dạng lỗi

Mọi lỗi đều là JSON với tối thiểu:

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

Nhiều phản hồi lỗi cũng bao gồm một đối tượng details — details.fields (một mảng tên các trường vi phạm) trên validation_failed, và details.allowed (cùng với from/to) trên 422 invalid_transition. Hãy dùng chúng.

Phân trang

Các endpoint danh sách chấp nhận limit và cursor. Cursor là không trong suốt (opaque); truyền next_cursor từ phản hồi trước. Các header phản hồi cũng bao gồm X-Tracker-Pagination-Total cho tổng số đếm ở những nơi rẻ để tính toán.

Tiếp theo là gì

• Đặc tả API — Mọi endpoint, mọi verb, mọi cấu trúc.
• Hướng dẫn vận hành → Agent — Phía giao diện: phát hành agent key, đặt tên agent, thu hồi.
• Giới thiệu — Các khái niệm đằng sau API: story, trạng thái, iteration, velocity, agent.