คู่มือ API

API ของ East Agile Tracker ออกแบบมาสำหรับเอเจนต์พอ ๆ กับมนุษย์ ทุกอย่างที่คุณทำได้ใน UI คุณทำได้ผ่าน API — และมีบางอย่างที่ UI ไม่ได้เปิดเผยอยู่ที่นี่ด้วย

คู่มือนี้พาคุณจากศูนย์ไปสู่ “การเขียนสคริปต์ backlog ของคุณ” ในเวลาไม่ถึงสิบนาที สำหรับเอกสารอ้างอิง endpoint แบบเต็ม ดู ข้อกำหนด API

คีย์สองชนิด

คุณยืนยันตัวตนด้วย คีย์ API ใน header X-TrackerToken มีอยู่สองชนิด:

• คีย์ผู้ใช้ (User keys) (ea_user_…) — ทำหน้าที่เป็น คุณ สร้างมันใน Account Settings → API Keys ใช้สำหรับสคริปต์ส่วนตัว เครื่องมือ CLI การผสานรวม
• คีย์เอเจนต์ (Agent keys) (ea_agent_…) — ทำหน้าที่เป็น เอเจนต์ที่มีชื่อในหนึ่งโปรเจกต์ สร้างมันในฐานะเจ้าของโปรเจกต์ใน Project Settings → Agents ใช้สำหรับเอเจนต์ AI — Claude Code, Codex หรือของคุณเอง — ที่ควรมีส่วนร่วมในโปรเจกต์ในฐานะเพื่อนร่วมทีมที่มีชื่อ

ความแตกต่าง:

	คีย์ผู้ใช้	คีย์เอเจนต์
ขอบเขต	ทุกโปรเจกต์ของคุณ	หนึ่งโปรเจกต์เฉพาะ
ตัวตนในบันทึกการตรวจสอบ	ชื่อของคุณ	ชื่อของเอเจนต์
บทบาท	บทบาทของคุณในแต่ละโปรเจกต์	กำหนดตอนสร้างคีย์ (viewer หรือ member)
การเพิกถอน	เพิกถอนคีย์ คุณยังเข้าถึงได้ผ่านคีย์/เซสชันอื่น	เพิกถอนคีย์ เอเจนต์เสียสิทธิ์เข้าถึงทันที
เหมาะที่สุดสำหรับ	การทำงานอัตโนมัติส่วนตัว สคริปต์	เอเจนต์ AI ที่ควรแยกแยะจากคุณได้ในประวัติ

Authorization: Bearer … ก็ใช้ได้หากคุณชอบสไตล์ header นั้น

สวัสดี 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 และค่าเริ่มต้นใด ๆ ที่เซิร์ฟเวอร์ใช้ (มาตรวัดการประเมิน สถานะเสร็จ ฯลฯ)

สร้าง 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"]
  }'

เลื่อน story ผ่านวงจรชีวิต

endpoint การเปลี่ยนสถานะ (transition) ตรวจสอบการย้ายที่ร้องขอและคืนสถานะถัดไปที่อนุญาตเมื่อเกิดข้อผิดพลาด:

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 และเลือกการย้ายถัดไปที่ถูกต้องได้โดยไม่ต้องขูดข้อมูลจากร้อยแก้ว

แสดงความคิดเห็นบน 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." }'

ความคิดเห็นถูกระบุให้กับใครก็ตามที่เป็นเจ้าของคีย์ API — หากเป็นคีย์เอเจนต์ ผู้เขียนความคิดเห็นคือเอเจนต์

การเขียนที่ทำซ้ำได้อย่างปลอดภัย (Idempotent writes)

ทุก endpoint การเขียนรับ header Idempotency-Key ลองใหม่ด้วยคีย์เดียวกันและ body เดียวกัน จะได้การตอบกลับเดิม ลองใหม่ด้วยคีย์เดียวกันแต่ body ต่างกัน จะได้ 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" }'

นี่สำคัญมากสำหรับเอเจนต์ในลูปลองใหม่ — แครชกลางการเขียน ลองใหม่ด้วยคีย์เดียวกัน ไม่มี story ซ้ำ

การเปลี่ยนสถานะเป็นกลุ่ม

ย้ายหลาย story พร้อมกัน แต่ละ story ถูกตัดสินอย่างอิสระ การย้ายที่ไม่ถูกต้องหนึ่งครั้งไม่ทำให้อันอื่นล้มเหลว

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

ติดตามสตรีมเหตุการณ์

สำหรับเอเจนต์ที่ต้องการตอบสนองต่อสิ่งที่มนุษย์ทำ ให้ 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"

การตอบกลับเป็นสตรีมเหตุการณ์ที่แบ่งหน้าด้วย cursor พร้อมผู้กระทำ ทรัพยากร และการเปลี่ยนแปลง แต่ละเหตุการณ์มี 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"

ตัวกรองที่มีให้:

ตัวกรอง	ตัวอย่าง	คำอธิบาย
type:	type:feature	กรองตามประเภท story
state:	state:started	กรองตามสถานะ
label:	label:"my label"	กรองตามป้ายกำกับ
owner:	owner:claire	กรองตามเจ้าของ
requester:	requester:tomas	กรองตามผู้ขอ
has:	has:blocker	story ที่มีตัวขัดขวาง
is:	is:unestimated	feature ที่ยังไม่ประเมิน

ข้อความอิสระจับคู่กับชื่อเรื่องและคำอธิบาย รวมตัวกรองโดยคั่นด้วยช่องว่าง — มันถูก 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 การค้นหาข้อมูลอ้างอิง (/story_types, /story_states, /effort_scales) ก็ไม่ต้องยืนยันตัวตนเช่นกัน เมื่อรวมกันแล้ว พวกมันให้เอเจนต์ตอบ “ฉันทำอะไรได้บ้างที่นี่?” โดยไม่ต้องเจอ 403 จากการลองผิดลองถูก

หมายเหตุ: openapi.json ที่ให้บริการแสดงรายการ path แต่ปัจจุบันส่ง request body ว่างเปล่า — ใช้รูปแบบฟิลด์ใน ข้อกำหนด สำหรับการเขียน

การควบคุมผ่าน 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 ด้วย — details.fields (อาร์เรย์ ของชื่อฟิลด์ที่ผิด) บน validation_failed และ details.allowed (คู่กับ from/to) บน 422 invalid_transition ใช้พวกมัน

การแบ่งหน้า (Pagination)

endpoint แบบรายการรับ limit และ cursor cursor เป็นแบบทึบ ส่ง next_cursor จากการตอบกลับก่อนหน้า header การตอบกลับยังรวม X-Tracker-Pagination-Total สำหรับจำนวนรวมในที่ที่คำนวณได้ราคาถูก

ขั้นต่อไป

• ข้อกำหนด API — ทุก endpoint ทุก verb ทุกรูปแบบ
• คู่มือการใช้งาน → เอเจนต์ — ฝั่ง UI: การสร้างคีย์เอเจนต์ การตั้งชื่อเอเจนต์ การเพิกถอน
• บทนำ — แนวคิดเบื้องหลัง API: story, สถานะ, รอบงาน, ความเร็ว, เอเจนต์