Spesifikasi API

Referensi endpoint REST lengkap. Untuk tutorial dan contoh, lihat Panduan API.

Segala sesuatu yang dapat dilakukan member proyek di UI web tersedia di sini — SPA mengonsumsi API yang sama ini. Operasi yang memerlukan peran owner ditandai (owner); selebihnya hanya membutuhkan keanggotaan proyek (atau, untuk pembacaan yang ditandai (viewer), tingkat akses apa pun).

Basis

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 menyajikan API yang identik. Semua request dan respons berupa JSON, kecuali beberapa endpoint unggah-file yang menerima multipart.

Autentikasi

Setiap request terautentikasi mengirim kunci API melalui salah satu dari:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Kunci pengguna dimulai dengan ea_user_. Kunci agen dimulai dengan ea_agent_. Lihat Panduan API → Dua jenis kunci.

Endpoint tidak terautentikasi: /openapi.json, /docs, endpoint /auth/*, dan lookup data-referensi (/story_types, /story_states, /effort_scales, …). /meta bersifat terautentikasi — kunci valid apa pun berfungsi, tetapi tidak dicakup-proyek (kunci agen yang terikat-proyek pun menjangkaunya).

Peran

Tiga tingkat menggerbangi endpoint yang dicakup-proyek:

Tingkat	Siapa yang lolos	Operasi tipikal
viewer	viewer, member, owner	pembacaan (daftar/dapatkan story, pencarian, analitik)
member	member, owner	semua write work-item (story, task, komentar, …)
owner	hanya owner	pengaturan proyek, manajemen keanggotaan, kunci agen, hapus, impor, log audit

Non-member menerima 404 unfound_resource (bukan 403) pada path proyek, sehingga ID proyek tidak dapat dienumerasi.

Endpoint yang mendeskripsikan diri

Metode	Path	Deskripsi
GET	/openapi.json	Spesifikasi OpenAPI 3 langsung. Tidak terautentikasi.
GET	/docs	Swagger UI. Tidak terautentikasi.
GET	/meta	Identitas pemanggil (auth.kind/key_id/agent_id/project_id) + graf transisi tipe-story. Terautentikasi (kunci valid apa pun; tidak dicakup-proyek). Panggil ini lebih dulu.

Akun / identitas

Ini bertindak pada pemanggil dan hanya membutuhkan kunci valid (tanpa peran proyek).

Metode	Path	Deskripsi
POST	/auth/register	Daftarkan akun baru
POST	/auth/login	Masuk, mengembalikan token sesi
POST	/auth/logout	Keluar
POST	/auth/forgot-password	Minta email reset-kata-sandi
POST	/auth/reset-password	Gunakan token reset untuk menetapkan kata sandi baru
GET	/auth/verify-email	Verifikasi alamat email
POST	/auth/accept-invite/lookup	Selesaikan token undangan → email (tidak terautentikasi)
POST	/auth/accept-invite	Terima undangan proyek (setelah autentikasi)
GET	/me	Profil pengguna saat ini
PUT	/me	Perbarui profil
DELETE	/me	Hapus akun
PUT	/me/password	Ubah kata sandi
PUT	/me/settings	Perbarui pengaturan (tema, preferensi notifikasi)
POST	/me/avatar	Unggah avatar (multipart)
POST	/me/api-token/regenerate	Rotasi token API Anda — membatalkan sesi/kunci yang ada
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Kelola kunci API pengguna (ea_user_)
GET	/me/activity	Aktivitas Anda di semua proyek
GET	/me/data-export	Ekspor-mandiri GDPR atas data Anda
GET	/me/consent · POST /me/consent	Baca / catat persetujuan ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Dokumen clickwrap tertunda / catat penerimaan
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Kontak + umpan balik dalam-aplikasi

Data referensi (tidak terautentikasi)

Lookup benih yang digunakan saat membuat/mengestimasi story. ID stabil.

Metode	Path	Deskripsi
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	skala estimasi yang tersedia
GET	/effort_scales/{scale_id}/values	nilai poin dalam suatu skala

Proyek

Metode	Path	Deskripsi
GET	/projects	Daftar proyek Anda
POST	/projects	Buat proyek
GET	/projects/{id}	Dapatkan detail proyek (viewer)
PUT	/projects/{id}	Perbarui pengaturan proyek (owner)
DELETE	/projects/{id}	Hapus proyek (owner)
GET	/projects/{id}/audit-log	Aliran aktivitas proyek (owner)
GET	/projects/{id}/events	Aliran event dengan paginasi-kursor (viewer) — lihat Event

Anggota dan kunci agen

Metode	Path	Deskripsi
GET	/projects/{id}/memberships	Daftar anggota (viewer)
POST	/projects/{id}/memberships	Undang anggota lewat email (owner)
PUT	/projects/{id}/memberships/{mid}	Perbarui peran (owner)
DELETE	/projects/{id}/memberships/{mid}	Hapus anggota (owner)
GET / POST	/projects/{id}/agent_keys	Daftar / cetak kunci agen (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Cabut kunci agen (owner)

Story

Semua write story membutuhkan peran member.

Metode	Path	Deskripsi
GET	/projects/{id}/stories	Daftar story (terpaginasi, dapat difilter) (viewer)
POST	/projects/{id}/stories	Buat story
GET	/projects/{id}/stories/{sid}	Dapatkan satu story (viewer)
PUT	/projects/{id}/stories/{sid}	Perbarui story
DELETE	/projects/{id}/stories/{sid}	Hapus story
POST	/projects/{id}/stories/{sid}/transitions	Ubah status dengan validasi
POST	/projects/{id}/stories/bulk_transition	Transisikan banyak story (1–100) sekaligus
POST	/projects/{id}/stories/bulk-delete	Hapus banyak story
POST	/projects/{id}/stories/bulk-duplicate	Duplikat banyak story
POST	/projects/{id}/stories/{sid}/duplicate	Duplikat satu story

Create (POST …/stories): { "name" (wajib), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels menerima ["auth"] atau [{ "name": "auth" }]; label yang tidak dikenal akan dibuat. Default: story_type=feature, current_state=unstarted.

Update (PUT …/stories/{sid}): field yang sama, semua opsional, plus "position" (float) dan "force_state_change" (bool).

Transition (POST …/transitions): { "to": "<state>", "reason"? }. Field-nya adalah to. Mengembalikan { story_id, state }. Pergerakan ilegal → 422 invalid_transition dengan details: { from, to, allowed }.

Bulk transition (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Setiap story dinilai secara independen; mengembalikan { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Sub-sumber daya story

Semua member. List/GET pada sebagian besar adalah (viewer).

Metode	Path	Body / catatan
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (atau task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (atau comment_text) } atau { comment_emoji }
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · DELETE …/links/{lid}	{ url, link_type?, title? }
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	{ reviewer_id? / reviewer_agent_id?, status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — hilangkan keduanya untuk menambahkan pemanggil
GET / POST	/projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid}	{ member_id? / agent_id? }
GET / POST	/projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	unggah multipart (≤ 2 GB masing-masing); daftar adalah (viewer)

Label

member untuk write, (viewer) untuk pembacaan.

Metode	Path	Deskripsi
GET / POST	/projects/{id}/labels	Daftar / buat label
PUT / DELETE	/projects/{id}/labels/{lid}	Perbarui / hapus label
POST	/projects/{id}/labels/{lid}/archive	Arsipkan (sembunyikan-lunak) label

Iterasi

Metode	Path	Deskripsi
GET	/projects/{id}/iterations	Daftar iterasi (member)
POST	/projects/{id}/iterations	Buat iterasi manual (owner)
DELETE	/projects/{id}/iterations/{itid}	Hapus iterasi (owner)

Pencarian, analitik, metrik, preferensi

Metode	Path	Deskripsi
GET	/projects/{id}/search?query=…	Pencarian sintaks filter (viewer) — lihat Panduan
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analitik (viewer). Penelusuran iterasi menerima ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrik (viewer)
GET / PUT	/projects/{id}/preferences	Preferensi papan Anda untuk proyek ini (member)

Event

Metode	Path	Deskripsi
GET	/projects/{id}/events	Aliran event dengan paginasi-kursor (viewer)

Parameter kueri: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Respons menyertakan next_cursor. Berikan event_id terakhir yang Anda lihat sebagai since untuk melanjutkan.

Impor (owner)

Metode	Path	Deskripsi
POST	/projects/{id}/import (+ /json)	Unggah multipart. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

Untuk kontrol-jarak-jauh UI interaktif ({ "action": "get_state", "id": "req-1" }). Bukan kanal data — semua pembacaan/write melalui REST. Hanya instans-tunggal; tidak disebarkan lintas replika.

Idempotensi

Endpoint write (POST, PUT, DELETE) menerima header Idempotency-Key. Kunci sama + body sama memutar ulang respons yang ter-cache (jendela 24-jam); kunci sama + body berbeda mengembalikan 409 idempotency_conflict. Tidak diterapkan pada GET/HEAD/OPTIONS, /auth/*, atau path /attachments. Respons 5xx tidak pernah di-cache — sebuah coba-ulang mencapai handler.

Paginasi

Endpoint daftar menerima cursor=<opaque> dan limit=<n≤200>. Saat diatur, responsnya adalah { "items": [...], "next_cursor": "<str|null>" }; berikan next_cursor kembali untuk halaman berikutnya. Beberapa daftar juga mengembalikan header X-Tracker-Pagination-Total.

Proyeksi field

Endpoint daftar menerima fields= (dipisahkan koma) untuk mengembalikan hanya field tertentu. story_id selalu disertakan; nama field yang tidak dikenal mengembalikan 400 validation_failed dengan nama yang menyalahi di details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Format error

Setiap error JSON memiliki code dan error; beberapa menambahkan details:

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

Status	code	Kapan
400	invalid_parameter	input buruk; pesan di error, tanpa details (sebagian besar validasi: kosong/panjang/null-byte/email)
400	validation_failed	error input terstruktur; details.fields adalah array nama field yang menyalahi
401	unauthenticated	token hilang/tidak valid
403	unauthorized_operation	terautentikasi tetapi peran tidak mencukupi
404	unfound_resource	tidak ditemukan — juga dikembalikan ke non-member
409	conflict	konflik sumber daya (mis. duplikat)
409	idempotency_conflict	Idempotency-Key digunakan ulang dengan body berbeda
422	invalid_transition	pergerakan status ilegal; details membawa { from, to, allowed }
500	internal_error	kesalahan server — pesan generik; aman untuk dicoba-ulang

details.fields adalah array JSON nama field (mis. ["to"]), kadang dengan kunci tambahan seperti max. Tidak ada peta field→pesan.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Batas laju

Per-kunci (per-IP untuk endpoint tidak terautentikasi), token bucket GCRA:

• Auth — /auth/*: 0,5 req/d, burst 20.
• Public — /contact, /feedback: 0,2 req/d, burst 10.
• Sensitive — reset-kata-sandi: ~0,002 req/d, burst 5.

Batas yang terlampaui mengembalikan 429 Too Many Requests dengan header Retry-After dan body teks-biasa (bukan amplop error JSON).