Panduan API

API East Agile Tracker dirancang untuk agen sebanyak untuk manusia. Segala sesuatu yang dapat Anda lakukan di UI, dapat Anda lakukan lewat API — dan beberapa hal yang tidak ditampilkan UI ada di sana juga.

Panduan ini membawa Anda dari nol ke “menulis skrip untuk backlog Anda” dalam waktu kurang dari sepuluh menit. Untuk referensi endpoint lengkap, lihat Spesifikasi API.

Tiga jenis kredensial

Anda mengautentikasi dengan sebuah kunci di header X-TrackerToken. Ada dua jenis kunci yang Anda cetak sendiri, dan jenis ketiga yang diperoleh klien MCP untuk Anda:

Kunci pengguna (ea_user_…) — Bertindak sebagai Anda. Buat di Account Settings → API Keys. Gunakan ini untuk skrip pribadi, alat CLI, integrasi.
Kunci agen (ea_agent_…) — Bertindak sebagai agen bernama dalam satu proyek. Buat di Project Settings → Agents. Gunakan ini untuk agen AI — Claude Code, Codex, milik Anda sendiri — yang harus berpartisipasi dalam proyek sebagai rekan setim bernama.
Token MCP (ea_mcp_…) — Token akses OAuth 2.1 yang diterbitkan untuk klien MCP (Claude, sebuah IDE) setelah Anda menyetujuinya di halaman persetujuan. Token ini bertindak sebagai Anda, dan Anda dapat mencabutnya di Account Settings → Connected apps.

Dialog sekali tampil setelah membuat kunci API pribadi di Pengaturan Akun, dengan kunci disamarkan di tangkapan ini

Formulir pembuatan kunci di tab Agent dengan nama dan peran member dipilih, di bawah petunjuk penyiapan

Perbedaan antara dua jenis yang Anda cetak:

	Kunci pengguna	Kunci agen
Lingkup	Semua proyek Anda	Satu proyek tertentu
Identitas di log audit	Nama Anda	Nama agen
Peran	Peran Anda di setiap proyek	Diatur saat pembuatan kunci (viewer, member, atau manager — tidak pernah di atas peran anggota yang mencetaknya)
Pencabutan	Cabut kunci; Anda tetap punya akses lewat kunci/sesi lain	Cabut atau rotasi kunci; agen kehilangan akses seketika
Paling cocok untuk	Otomasi pribadi, skrip	Agen AI yang harus dapat dibedakan dari Anda dalam riwayat

Authorization: Bearer … juga berfungsi jika Anda lebih suka gaya header itu.

Halo, API

Dapatkan proyek Anda:

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

Atau untuk kunci agen, daftarkan proyek yang menjadi cakupannya:

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

API adalah JSON, REST-ish, diberi versi di /api/v1/. Bentuk yang sama untuk manusia dan agen.

Membuat proyek

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 mencakup project_id dan default apa pun yang diterapkan server (skala estimasi, done state, dst.).

Membuat 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 adalah label nilai skala sebagai string — "3", atau "13" pada skala Fibonacci — karena ia harus cocok dengan salah satu titik pada skala proyek. Angka JSON ditolak.

Menggerakkan story melalui daur hidup

Endpoint transisi memvalidasi pergerakan yang diminta dan mengembalikan status berikutnya yang diizinkan saat error:

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

Field-nya adalah to (bukan to_state). Jika pergerakan ilegal — misalnya Anda mencoba melompat dari unstarted langsung ke accepted — responsnya adalah 422 invalid_transition dengan detail error terstruktur:

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

Ini adalah salah satu hal kecil yang membuat API ramah-agen: sebuah agen dapat membaca details.allowed dan memilih pergerakan berikutnya yang tepat tanpa mengikis prosa.

rejected bersifat terminal bagi endpoint transisi. Untuk mengembalikan story yang ditolak ke pengerjaan, POST …/stories/{sid}/restart; POST …/stories/{sid}/reject adalah bentuk verb untuk menolak story yang sudah delivered.

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

Komentar diatribusikan kepada siapa pun yang memiliki kunci API — jika itu kunci agen, penulis komentar adalah agen.

Write idempoten

Setiap endpoint write menerima header Idempotency-Key. Coba ulang kunci yang sama dengan body yang sama, dapatkan respons yang sama kembali. Coba ulang kunci yang sama dengan body berbeda, 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 krusial untuk agen dalam loop coba-ulang — crash di tengah-write, coba ulang dengan kunci yang sama, tanpa story duplikat.

Transisi massal

Pindahkan banyak story sekaligus. Setiap story dinilai secara independen; satu pergerakan ilegal 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"
  }'

Mengikuti aliran event

Untuk agen yang ingin bereaksi terhadap apa yang dilakukan manusia, polling endpoint event:

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 adalah aliran event dengan paginasi-kursor berisi aktor, sumber daya, dan perubahan. Setiap event memiliki ID; berikan ID terakhir yang Anda lihat sebagai since untuk melanjutkan dari tempat Anda berhenti. Tanpa webhook, tanpa pengikisan, tanpa event yang terlewat. Aliran ini memerlukan peran member — viewer mendapat 403.

Pencarian

GET /projects/{id}/search?q=<query> menjalankan pencarian teks-penuh + terstruktur yang kuat atas story proyek. Bahasa kuerinya dimodelkan dari qualifier pencarian issue GitHub — jadi sintaks yang sudah Anda (atau agen AI) kenal dari GitHub sebagian besar bisa dipakai di sini.

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'

Responsnya adalah amplop JSON, story diperingkat berdasarkan relevansi:

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

total adalah jumlah kecocokan penuh, bukan ukuran halaman. Paginasi dengan limit (default 50, maks 1000) dan offset; urutkan dengan sort=relevance (default), created, created_asc, updated, atau state.

Tata bahasa

Teks bebas mencocokkan judul, referensi, dan deskripsi story (teks-penuh, di-stem dan diperingkat). Bungkus frasa persis dalam "tanda kutip".
Qualifier berbentuk field:value. Pisahkan alternatif dengan koma (OR dalam satu field): type:bug,chore. Pisahkan qualifier dengan spasi (AND antar qualifier).
Negasikan term atau qualifier apa pun dengan awalan -: -label:wontfix.
Rentang untuk tanggal dan poin: inklusif a..b, atau terbuka >x / <x.

Qualifier

Qualifier	Contoh	Mencocokkan
`type:`	`type:bug,chore`	tipe story
`state:`	`state:started,finished`	status alur kerja
`label:`	`label:"my label"`	sebuah label
`epic:`	`epic:"Checkout"`	story dalam sebuah epic
`priority:`	`priority:p1`	prioritas
`points:`	`points:3` · `points:1..5` · `points:>3`	nilai atau rentang estimasi
`iteration:`	`iteration:42`	id iterasi
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	sebuah tanggal atau rentang (granularitas hari); `release:` adalah tanggal release story
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	seseorang berdasarkan nama atau email — anggota dan agen, termasuk `mention:`; `@me` adalah Anda
`has:blocker`	`has:blocker`	memiliki blocker terbuka
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	sebuah flag

mywork: adalah alias untuk owner: — mywork:me sama dengan owner:@me. Qualifier scheduled: yang lama sudah dipensiunkan dan diabaikan diam-diam; gunakan release:.

Koma-OR (type:bug,chore) berlaku untuk qualifier facet; qualifier orang (owner: requester: follower: reviewer: commenter: mention:) menerima satu nilai.

Contoh

payment crash                              teks penuh "payment" DAN "crash"
"exact phrase"                             sebuah frasa
type:bug,chore state:started               bug atau chore yang sudah started
owner:@me -label:wontfix                   milik saya, tanpa label wontfix
points:3..8 created:2026-05-01..2026-06-01 estimasi 3-8, dibuat pada Mei
follower:tomas has:blocker                 tomas mengikutinya dan ia diblokir
is:backlog updated:>2026-06-01             item backlog yang disentuh sejak 1 Jun

String kueri yang sama menggerakkan kotak pencarian papan (yang membuka kolom hasil langsung) dan API ini — satu tata bahasa untuk manusia dan agen. Pencarian isi komentar, task, dan blocker ada di roadmap; hari ini teks bebas mencakup judul, referensi, dan deskripsi story itu sendiri.

Menemukan API

Spesifikasi OpenAPI 3 langsung ada di:

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

Swagger UI ada di:

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

/openapi.json dan /docs tidak terautentikasi — sebuah agen dapat membaca kontrak sebelum ia memiliki kunci. Setelah ia memegang kunci, /api/v1/meta (yang memerlukan kunci valid) mengembalikan identitasnya dan graf transisi per-tipe-story; lookup data-referensi (/story_types, /story_states, /effort_scales, /priority_scales) juga tidak terautentikasi. Bersama-sama mereka memungkinkan agen menjawab “apa yang dapat saya lakukan di sini?” tanpa 403 coba-coba.

openapi.json yang disajikan memuat skema request body untuk endpoint write, termasuk maxLength setiap field, sehingga klien dapat memvalidasi sebelum mengirim. Spesifikasi merangkum bentuk-bentuk yang sama.

Kontrol WebSocket

Untuk otomasi interaktif — mengendalikan sesi browser yang sudah masuk dari skrip, atau mengontrol UI dari jarak jauh untuk tutorial — ada kanal WebSocket:

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

token adalah JWT sesi browser, bukan kunci API — kunci ea_user_* atau ea_agent_* ditolak sebelum upgrade. Sebagian besar pengguna tidak pernah membutuhkan ini; ia ada untuk kasus di mana REST tidak cukup.

Mengimpor dari tracker lain

Jika Anda menulis skrip untuk migrasi massal:

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 file yang didukung: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (ekspor East Agile Tracker sendiri — format round-trip). Endpoint multipart berjalan sinkron dan menjawab dengan hitungan hasil.

GitHub mengimpor dari API alih-alih dari file, lewat endpoint JSON — tanpa file, cukup 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 bersifat asinkron: ia menjawab 202 dengan { "import_id", "status" } dan Anda mem-poll GET /projects/{id}/imports/{import_id} sampai job mencapai done atau failed. Hanya satu impor berjalan per proyek pada satu waktu — panggilan kedua saat satu masih berjalan adalah 409 import_already_running. Seluruh loopnya, dengan field progres job, ada di Mengisi proyek dari repo GitHub.

token bersifat opsional dalam permintaan, tetapi pengambilannya sendiri selalu melakukan autentikasi — ia berjalan di API GraphQL GitHub, yang tidak punya tingkat anonim. Hilangkan token dan server akan memakai token platformnya: hanya repositori publik, dipakai bersama oleh setiap pemanggil, dan ditolak dengan import_github_shared_quota_low ketika anggaran GraphQL-nya turun di bawah 500 poin. Repositori privat, atau deployment yang tidak mengonfigurasi token platform (import_github_no_token), menuntut token Anda. Token mana pun yang dipakai, ia hanya digunakan untuk panggilan GitHub hulu dan tidak pernah disimpan atau digemakan kembali. Rincian lengkapnya, termasuk plafon REST tanpa autentikasi sebesar 60 permintaan dari GitHub, ada di Mengisi proyek dari repo GitHub.

Pratinjau dry-run. Tambahkan "dry_run": true (JSON) atau -F "dry_run=true" (multipart) ke sumber apa pun. Impor mengurai, menyelesaikan, dan mendeduplikasi persis seperti jalannya yang sungguhan, menghasilkan hitungan hasil yang sama (imported, skipped, errors, unmatched), lalu membatalkan semuanya — tanpa apa pun yang ditulis. Pada endpoint JSON hitungannya tiba pada job yang di-poll, dry run atau bukan.

Batas. Body unggahan dibatasi pada 10 MiB, dan satu impor pada 5.000 story; melampaui salah satunya adalah 400 tanpa apa pun yang ditulis. Mengimpor ulang sebuah file itu aman — baris yang sudah diimpor (dicocokkan berdasarkan source id) dilewati, bukan diduplikasi.

Mengekspor proyek

Peran proyek mana pun dapat mendaftar formatnya; mengunduh satu format hanya untuk owner:

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

# Unduh satu format (eat adalah CSV round-trip berkesetiaan penuh)
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, plus format dokumen pdf dan docx. Setiap lampiran dapat diunduh sebagai satu zip dari GET /projects/{id}/export/attachments.

Format error

Semua error berupa JSON dengan minimal:

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

Banyak respons error juga menyertakan objek details — details.fields (sebuah array nama field yang menyalahi) pada validation_failed, dan details.allowed (di samping from/to) pada 422 invalid_transition. Gunakan mereka. 429 rate_limited membawa header Retry-After dalam amplop JSON yang sama.

Paginasi

Endpoint daftar menerima limit dan cursor. Cursor bersifat opak; berikan next_cursor dari respons sebelumnya. Batas limit berbeda per endpoint — 200 pada story, komentar, dan proyek, 500 pada event, 1000 pada pencarian dan log audit. Daftar biasa (non-cursor) yang harus memotong responsnya menyatakannya lewat header: X-Tracker-Pagination-Truncated, -Limit, -Offset, dan -Next-Offset, yang Anda kirim balik sebagai offset= untuk halaman berikutnya. Tidak ada header jumlah total.

Apa selanjutnya

Spesifikasi API — Setiap endpoint, setiap verb, setiap bentuk.
Petunjuk Pengoperasian → Agen — Sisi-UI: mencetak kunci agen, memberi nama agen, mencabut.
Pengantar — Konsep di balik API: story, status, iterasi, velocity, agen.