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.

Dua jenis kunci

Anda mengautentikasi dengan kunci API di header X-TrackerToken. Ada dua jenis:

• 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 sebagai owner proyek di Project Settings → Agents. Gunakan ini untuk agen AI — Claude Code, Codex, milik Anda sendiri — yang harus berpartisipasi dalam proyek sebagai rekan setim bernama.

Perbedaannya:

	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 atau member)
Pencabutan	Cabut kunci; Anda tetap punya akses lewat kunci/sesi lain	Cabut 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"]
  }'

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.

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.created" \
  -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.

Mencari dengan sintaks filter

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

Filter yang tersedia:

Filter	Contoh	Deskripsi
type:	type:feature	Filter berdasarkan tipe story
state:	state:started	Filter berdasarkan status
label:	label:"my label"	Filter berdasarkan label
owner:	owner:claire	Filter berdasarkan pemilik
requester:	requester:tomas	Filter berdasarkan requestor
has:	has:blocker	Story dengan blocker
is:	is:unestimated	Feature yang belum diestimasi

Teks bebas mencocokkan judul dan deskripsi. Gabungkan filter dengan memisahkannya dengan spasi — mereka di-AND-kan.

Menemukan API

Spesifikasi OpenAPI 3 langsung ada di:

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

Swagger UI ada di:

https://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) juga tidak terautentikasi. Bersama-sama mereka memungkinkan agen menjawab “apa yang dapat saya lakukan di sini?” tanpa 403 coba-coba.

Catatan: openapi.json yang disajikan mencantumkan path tetapi saat ini mengirim request body kosong — gunakan bentuk field di Spesifikasi untuk write.

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

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 yang didukung: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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.

Paginasi

Endpoint daftar menerima limit dan cursor. Cursor bersifat opak; berikan next_cursor dari respons sebelumnya. Header respons juga menyertakan X-Tracker-Pagination-Total untuk jumlah total di mana murah untuk dihitung.

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.