Panduan API

API East Agile Tracker direka bentuk untuk ejen sama seperti untuk manusia. Segala yang anda boleh lakukan dalam UI, anda boleh lakukan melalui API — dan beberapa perkara yang UI tidak dedahkan juga ada di sini.

Panduan ini membawa anda daripada sifar ke “memskrip backlog anda” dalam kurang sepuluh minit. Untuk rujukan endpoint penuh, lihat Spesifikasi API.

Dua jenis kunci

Anda mengesahkan dengan kunci API dalam pengepala X-TrackerToken. Terdapat dua jenis:

• Kunci pengguna (ea_user_…) — Bertindak sebagai anda. Cipta ia dalam Account Settings → API Keys. Gunakan ini untuk skrip peribadi, alat CLI, integrasi.
• Kunci ejen (ea_agent_…) — Bertindak sebagai ejen bernama dalam satu projek. Cipta ia sebagai pemilik projek dalam Project Settings → Agents. Gunakan ini untuk ejen AI — Claude Code, Codex, milik anda sendiri — yang harus mengambil bahagian dalam projek sebagai rakan sepasukan bernama.

Perbezaannya:

	Kunci pengguna	Kunci ejen
Skop	Semua projek anda	Satu projek tertentu
Identiti dalam log audit	Nama anda	Nama ejen
Peranan	Peranan anda dalam setiap projek	Ditetapkan semasa penciptaan kunci (viewer atau member)
Pembatalan	Batalkan kunci; anda kekal akses melalui kunci/sesi lain	Batalkan kunci; ejen kehilangan akses serta-merta
Terbaik untuk	Automasi peribadi, skrip	Ejen AI yang harus boleh dibezakan daripada anda dalam sejarah

Authorization: Bearer … juga berfungsi jika anda lebih suka gaya pengepala itu.

Helo, API

Dapatkan projek anda:

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

Atau untuk kunci ejen, senaraikan projek yang ia diskopkan:

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

API adalah JSON, REST-ish, berversi pada /api/v1/. Bentuk yang sama untuk manusia dan ejen.

Cipta projek

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

Respons termasuk project_id dan mana-mana lalai yang pelayan gunakan (skala anggaran, keadaan selesai, dll.).

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

Gerakkan story melalui kitaran hayat

Endpoint peralihan mengesahkan gerakan yang diminta dan memulangkan keadaan seterusnya yang dibenarkan apabila ralat:

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

Medan ialah to (bukan to_state). Jika gerakan tidak sah — katakan anda cuba melangkau daripada unstarted terus ke accepted — respons ialah 422 invalid_transition dengan butiran ralat berstruktur:

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

Ini ialah salah satu perkara kecil yang menjadikan API mesra-ejen: ejen boleh membaca details.allowed dan memilih gerakan seterusnya yang betul tanpa mengikis prosa.

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

Ulasan dikaitkan kepada sesiapa yang memiliki kunci API — jika ia kunci ejen, pengarang ulasan ialah ejen.

Penulisan idempoten

Setiap endpoint penulisan menerima pengepala Idempotency-Key. Cuba semula kunci yang sama dengan badan yang sama, dapatkan respons yang sama kembali. Cuba semula kunci yang sama dengan badan yang berbeza, dapatkan 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" }'

Ini kritikal untuk ejen dalam gelung cuba-semula — terhempas separuh jalan penulisan, cuba semula dengan kunci yang sama, tiada story pendua.

Peralihan pukal

Gerakkan banyak story sekaligus. Setiap story dihakimi secara bebas; satu gerakan tidak sah tidak menggagalkan yang lain.

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

Ikuti aliran peristiwa

Untuk ejen yang mahu bertindak balas terhadap apa yang manusia lakukan, tinjau endpoint peristiwa:

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"

Respons ialah aliran peristiwa berhalaman-kursor dengan pelaku, sumber, dan perubahan. Setiap peristiwa mempunyai ID; hantar ID terakhir yang anda lihat sebagai since untuk menyambung di tempat anda berhenti. Tiada webhook, tiada pengikisan, tiada peristiwa terlepas.

Cari dengan sintaks penapis

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

Penapis yang tersedia:

Penapis	Contoh	Penerangan
type:	type:feature	Tapis mengikut jenis story
state:	state:started	Tapis mengikut keadaan
label:	label:"my label"	Tapis mengikut label
owner:	owner:claire	Tapis mengikut pemilik
requester:	requester:tomas	Tapis mengikut requestor
has:	has:blocker	Story dengan blocker
is:	is:unestimated	Feature tidak dianggar

Teks bebas memadankan tajuk dan penerangan. Gabungkan penapis dengan memisahkannya dengan ruang — ia di-AND-kan.

Terokai API

Spesifikasi OpenAPI 3 langsung berada di:

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

Swagger UI berada di:

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

/openapi.json dan /docs adalah tidak disahkan — ejen boleh membaca kontrak sebelum ia mempunyai kunci. Sebaik sahaja ia memegang kunci, /api/v1/meta (yang memerlukan kunci yang sah) memulangkan identitinya dan graf peralihan setiap-jenis-story; carian rujukan-data (/story_types, /story_states, /effort_scales) juga tidak disahkan. Bersama-sama ia membenarkan ejen menjawab “apa yang saya boleh lakukan di sini?” tanpa 403 cuba-dan-ralat.

Nota: openapi.json yang dihidangkan menyenaraikan laluan tetapi pada masa ini menghantar badan permintaan kosong — gunakan bentuk medan dalam Spesifikasi untuk penulisan.

Kawalan WebSocket

Untuk automasi interaktif — memacu sesi pelayar yang dilog masuk daripada skrip, atau mengawal jauh UI untuk tutorial — terdapat saluran WebSocket:

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

Kebanyakan pengguna tidak pernah memerlukan ini; ia ada untuk kes-kes di mana REST tidak mencukupi.

Import daripada tracker lain

Jika anda memskrip migrasi pukal:

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"

Sumber yang disokong: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

Format ralat

Semua ralat adalah JSON dengan sekurang-kurangnya:

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

Banyak respons ralat juga termasuk objek details — details.fields (sebuah tatasusunan nama medan yang menyalahi) pada validation_failed, dan details.allowed (bersama from/to) pada 422 invalid_transition. Gunakannya.

Penghalamanan

Endpoint senarai menerima limit dan cursor. Cursor adalah legap; hantar next_cursor daripada respons sebelumnya. Pengepala respons juga termasuk X-Tracker-Pagination-Total untuk jumlah kiraan di mana murah untuk dikira.

Apa seterusnya

• Spesifikasi API — Setiap endpoint, setiap kata kerja, setiap bentuk.
• Arahan Pengendalian → Ejen — Pihak UI: mencetak kunci ejen, menamakan ejen, membatalkan.
• Pengenalan — Konsep di sebalik API: story, keadaan, iterasi, velocity, ejen.