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.

Tiga jenis bukti kelayakan

Anda mengesahkan dengan kunci dalam pengepala X-TrackerToken. Terdapat dua jenis kunci yang anda cetak sendiri, dan jenis ketiga yang diperoleh oleh klien MCP untuk anda:

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 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.
Token MCP (ea_mcp_…) — Token akses OAuth 2.1 yang dikeluarkan kepada klien MCP (Claude, IDE) selepas anda meluluskannya pada halaman persetujuan. Ia bertindak sebagai anda, dan anda boleh membatalkannya di bawah Account Settings → Connected apps.

Dialog sekali paparan selepas mencipta kunci API peribadi dalam Tetapan Akaun, dengan kunci disembunyikan dalam tangkapan ini

Borang cipta kunci dalam tab Agent dengan nama dan peranan member dipilih, di bawah arahan persediaan

Perbezaan antara dua jenis yang anda cetak sendiri:

	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, member, atau manager — tidak pernah melebihi peranan ahli yang mencetaknya)
Pembatalan	Batalkan kunci; anda kekal akses melalui kunci/sesi lain	Batalkan atau putar 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"]
  }'

estimate ialah label nilai skala sebagai rentetan — "3", atau "13" pada skala Fibonacci — kerana ia mesti sepadan dengan satu mata pada skala projek. Nombor JSON ditolak.

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.

rejected adalah terminal bagi endpoint peralihan. Untuk mengembalikan story yang ditolak kepada kerja, gunakan POST …/stories/{sid}/restart; POST …/stories/{sid}/reject ialah bentuk kata kerja untuk menolak story yang telah delivered.

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.added" \
  -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. Aliran ini memerlukan peranan member — viewer mendapat 403.

Carian

GET /projects/{id}/search?q=<query> menjalankan carian teks penuh + berstruktur yang berkuasa ke atas story projek. Bahasa pertanyaannya dimodelkan pada kelayakan carian issue GitHub — jadi sintaks yang anda (atau ejen AI) sudah kenali daripada GitHub kebanyakannya boleh terus digunakan.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

Respons ialah sampul JSON, dengan story disusun mengikut kerelevanan:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total ialah kiraan padanan penuh, bukan saiz halaman. Halamankan dengan limit (lalai 50, maksimum 1000) dan offset; susun dengan sort=relevance (lalai), created, created_asc, updated, atau state.

Tatabahasa

Teks bebas memadankan tajuk, rujukan, dan penerangan story (teks penuh, dengan stemming dan penyusunan kedudukan). Balut frasa tepat dalam "tanda petik".
Kelayakan berbentuk field:value. Pisahkan alternatif dengan koma (OR dalam satu medan): type:bug,chore. Pisahkan kelayakan dengan ruang (AND merentasinya).
Nafikan mana-mana istilah atau kelayakan dengan - di hadapan: -label:wontfix.
Julat untuk tarikh dan mata: inklusif a..b, atau terbuka >x / <x.

Kelayakan

Kelayakan	Contoh	Padanan
`type:`	`type:bug,chore`	jenis story
`state:`	`state:started,finished`	keadaan aliran kerja
`label:`	`label:"my label"`	satu label
`epic:`	`epic:"Checkout"`	story dalam satu epik
`priority:`	`priority:p1`	keutamaan
`points:`	`points:3` · `points:1..5` · `points:>3`	nilai atau julat anggaran
`iteration:`	`iteration:42`	id iterasi
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	satu tarikh atau julat (kebutiran hari); `release:` ialah tarikh release story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	seseorang mengikut nama atau e-mel — ahli dan ejen, termasuk `mention:`; `@me` ialah anda
`has:blocker`	`has:blocker`	mempunyai blocker terbuka
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	satu bendera

mywork: ialah alias bagi owner: — mywork:me ialah owner:@me. Kelayakan scheduled: yang lama sudah dihentikan dan diabaikan secara senyap; gunakan release:.

Koma-OR (type:bug,chore) terpakai pada kelayakan faset; kelayakan orang (owner: requester: follower: reviewer: commenter: mention:) menerima satu nilai sahaja.

Contoh

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

Rentetan pertanyaan yang sama memacu kotak carian papan (yang membuka lajur hasil langsung) dan API ini — satu tatabahasa untuk manusia dan ejen. Mencari kandungan ulasan, tugas, dan blocker ada dalam pelan hala tuju; hari ini teks bebas meliputi tajuk, rujukan, dan penerangan story itu sendiri.

Terokai API

Spesifikasi OpenAPI 3 langsung berada di:

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

Swagger UI berada di:

https://api.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, /priority_scales) juga tidak disahkan. Bersama-sama ia membenarkan ejen menjawab “apa yang saya boleh lakukan di sini?” tanpa 403 cuba-dan-ralat.

openapi.json yang dihidangkan membawa skema badan permintaan untuk endpoint penulisan, termasuk maxLength setiap medan, jadi klien boleh mengesahkan sebelum menghantar. Spesifikasi meringkaskan bentuk yang sama.

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=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

token ialah JWT sesi pelayar, bukan kunci API — kunci ea_user_* atau ea_agent_* ditolak sebelum naik taraf sambungan. 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 fail yang disokong: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (format eksport East Agile Tracker sendiri — format pergi-balik). Endpoint multipart berjalan secara segerak dan menjawab dengan kiraan hasil.

GitHub mengimport daripada API dan bukannya daripada fail, melalui endpoint JSON — tiada file, hanya koordinat repositori:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

Endpoint JSON adalah tak segerak: ia menjawab 202 dengan { "import_id", "status" } dan anda meninjau GET /projects/{id}/imports/{import_id} sehingga kerja itu mencapai done atau failed. Hanya satu import berjalan bagi setiap projek pada satu masa — panggilan kedua semasa satu sedang berjalan ialah 409 import_already_running. Keseluruhan gelung, dengan medan kemajuan kerja itu, ada dalam Mengisi projek daripada repo GitHub.

token adalah pilihan dalam permintaan, tetapi pengambilan itu sendiri sentiasa mengesahkan diri — ia berjalan pada API GraphQL GitHub, yang tiada peringkat tanpa nama. Tinggalkan token dan pelayan menggantikannya dengan token platformnya: repositori awam sahaja, dikongsi oleh setiap pemanggil, dan ditolak dengan import_github_shared_quota_low apabila bajet GraphQL-nya jatuh di bawah 500 mata. Repositori peribadi, atau deployment yang tidak mengkonfigurasi token platform (import_github_no_token), menuntut token anda. Token mana pun yang berjalan, ia digunakan hanya untuk panggilan GitHub huluan dan tidak pernah disimpan atau digemakan kembali. Perincian penuh, termasuk siling REST tanpa pengesahan sebanyak 60 permintaan pada GitHub, ada dalam Mengisi projek daripada repo GitHub.

Pratonton dry-run. Tambah "dry_run": true (JSON) atau -F "dry_run=true" (multipart) pada mana-mana sumber. Import menghurai, menyelesaikan, dan menyahduplikasi tepat seperti larian sebenar, menghasilkan kiraan hasil yang sama (imported, skipped, errors, unmatched), kemudian mengundur segalanya — tiada apa yang ditulis. Pada endpoint JSON, kiraan tiba pada kerja yang ditinjau, sama ada dry run atau tidak.

Had. Badan muat naik dihadkan pada 10 MiB, dan satu import pada 5,000 story; melebihi salah satu adalah 400 tanpa apa-apa ditulis. Mengimport semula fail adalah selamat — baris yang telah diimport (dipadankan mengikut id sumber) dilangkau, bukan diduplikasi.

Eksport projek

Mana-mana peranan projek boleh menyenaraikan format; memuat turun satu format adalah untuk pemilik sahaja:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Id format pertukaran: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, ditambah format dokumen pdf dan docx. Setiap lampiran boleh dimuat turun sebagai satu zip daripada GET /projects/{id}/export/attachments.

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. 429 rate_limited membawa pengepala Retry-After dalam sampul JSON yang sama.

Penghalamanan

Endpoint senarai menerima limit dan cursor. Cursor adalah legap; hantar next_cursor daripada respons sebelumnya. Had limit berbeza bagi setiap endpoint — 200 pada story, ulasan, dan projek, 500 pada peristiwa, 1000 pada carian dan log audit. Senarai biasa (bukan kursor) yang terpaksa memotong responsnya menyatakannya dalam pengepala: X-Tracker-Pagination-Truncated, -Limit, -Offset, dan -Next-Offset, yang anda hantar kembali sebagai offset= untuk halaman seterusnya. Tiada pengepala jumlah kiraan.

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.