API 指南

East Agile Tracker API 既为人类、也同等地为智能体而设计。凡是你能在 UI 中做的事，你都能通过 API 完成——而且还有一些 UI 不暴露的功能也在这里。

本指南会在十分钟内带你从零做到“脚本化你的待办列表”。完整的端点参考，请参阅 API 规范。

两种密钥

你通过 X-TrackerToken 请求头中的 API 密钥进行认证。共有两种：

• 用户密钥（ea_user_…）——以你本人的身份行事。在 Account Settings → API Keys 中创建。用于个人脚本、CLI 工具、集成。
• 智能体密钥（ea_agent_…）——以某个项目中的具名智能体的身份行事。以项目所有者身份在 Project Settings → Agents 中创建。用于那些应当作为具名队友参与项目的 AI 智能体——Claude Code、Codex、你自己的。

区别如下：

	User key	Agent key
Scope	你所有的项目	一个特定的项目
Identity in audit log	你的名字	该智能体的名字
Role	你在每个项目中的角色	创建密钥时设定（viewer 或 member）
Revocation	撤销一个密钥；你仍可通过其他密钥/会话保有访问权	撤销一个密钥；该智能体立刻失去访问权
Best for	个人自动化、脚本	应当在历史中与你相区分的 AI 智能体

如果你更喜欢那种请求头风格，Authorization: Bearer … 也行得通。

Hello, API

获取你的项目：

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

或者，对于一个智能体密钥，列出它所限定的那个项目：

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

API 是 JSON、REST 风格、在 /api/v1/ 处带版本。对人类和智能体是相同的数据形态。

创建一个项目

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

响应包含 project_id 以及服务器所应用的任何默认值（估算尺度、完成状态等）。

创建一个故事

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

让故事走过生命周期

流转端点会校验所请求的移动，并在出错时返回所允许的下一批状态：

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

字段是 to（不是 to_state）。如果这个移动非法——比如你试图从 unstarted 直接跳到 accepted——响应会是 422 invalid_transition，并附带结构化的错误详情：

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

这是让 API 对智能体友好的小细节之一：智能体可以读取 details.allowed，并选出正确的下一步移动，而无需去抓取散文。

在故事上评论

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

评论会被归因于持有该 API 密钥的人——如果是智能体密钥，评论的作者就是该智能体。

幂等写入

每个写入端点都接受一个 Idempotency-Key 请求头。用同一个密钥配同一个请求体重试，会拿回同一个响应。用同一个密钥配不同的请求体重试，会得到 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" }'

这对处于重试循环中的智能体至关重要——写入途中崩溃，用同一个密钥重试，不会产生重复的故事。

批量流转

一次移动许多故事。每个故事都被独立裁决；一个非法的移动不会让其余的失败。

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

追随事件流

对于想要对人类所做之事作出反应的智能体，轮询 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"

响应是一个以游标分页的事件流，包含操作者、资源和变更。每个事件都有一个 ID；把你看到的最后一个 ID 作为 since 传入，即可从你上次停下的地方继续。没有 webhook，没有抓取，没有遗漏的事件。

用筛选语法搜索

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

可用的筛选：

Filter	Example	Description
type:	type:feature	按故事类型筛选
state:	state:started	按状态筛选
label:	label:"my label"	按标签筛选
owner:	owner:claire	按负责人筛选
requester:	requester:tomas	按请求者筛选
has:	has:blocker	带阻碍的故事
is:	is:unestimated	未估算的功能

自由文本匹配标题和描述。用空格分隔来组合多个筛选——它们之间是 AND 关系。

探索 API

实时的 OpenAPI 3 规范在：

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

Swagger UI 在：

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

/openapi.json 和 /docs 无需认证——智能体在拥有密钥之前就能读到契约。一旦它持有了密钥，/api/v1/meta（它需要一个有效的密钥）会返回它的身份和逐故事类型的流转图；参考数据查询（/story_types、/story_states、/effort_scales）同样无需认证。它们合在一起，让智能体无需靠反复试错碰 403，就能回答“我在这里能做什么？”。

注意：所提供的 openapi.json 列出了路径，但目前交付的是空的请求体——写入时请使用规范中的字段形态。

WebSocket 控制

对于交互式自动化——从脚本驱动一个已登录的浏览器会话，或者为教程远程控制 UI——有一个 WebSocket 通道：

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

大多数用户从不需要它；它是为那些 REST 不够用的情形而准备的。

从另一款 tracker 导入

如果你正在脚本化一次批量迁移：

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"

支持的来源：pivotal、jira、asana、gitlab、shortcut、trello、linear、plane、plane_json。

错误格式

所有错误都是 JSON，至少包含：

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

许多错误响应还包含一个 details 对象——在 validation_failed 上有 details.fields（一个由出错字段名组成的数组），在 422 invalid_transition 上有 details.allowed（连同 from/to）。请善用它们。

分页

列表端点接受 limit 和 cursor。游标是不透明的；把上一个响应中的 next_cursor 传入。在计算开销不大时，响应头还会包含 X-Tracker-Pagination-Total 以给出总数。

接下来是什么

• API 规范——每个端点、每个动词、每种数据形态。
• 使用说明 → 智能体——UI 这一侧：铸造智能体密钥、为智能体命名、撤销。
• 简介——API 背后的概念：故事、状态、迭代、速率、智能体。