Spesifikasi API

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

Segala yang ahli projek boleh lakukan dalam UI web tersedia di sini — SPA menggunakan API yang sama ini. Operasi yang memerlukan peranan owner ditandakan (owner); segala yang lain hanya memerlukan keahlian projek (atau, untuk bacaan yang ditandakan (viewer), mana-mana tahap akses).

Asas

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 menghidangkan API yang serupa. Semua permintaan dan respons adalah JSON, kecuali beberapa endpoint muat-naik-fail yang menerima multipart.

Pengesahan

Setiap permintaan yang disahkan menghantar kunci API melalui salah satu daripada:

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

Kunci pengguna bermula dengan ea_user_. Kunci ejen bermula dengan ea_agent_. Lihat Panduan API → Dua jenis kunci.

Endpoint tidak disahkan: /openapi.json, /docs, endpoint /auth/*, dan carian rujukan-data (/story_types, /story_states, /effort_scales, …). /meta adalah disahkan — mana-mana kunci yang sah berfungsi, tetapi ia tidak berskop-projek (kunci ejen terikat-projek juga mencapainya).

Peranan

Tiga tahap mengawal endpoint berskop-projek:

Tahap	Siapa yang lulus	Operasi tipikal
viewer	viewer, member, owner	bacaan (senarai/dapat story, carian, analitik)
member	member, owner	semua penulisan item-kerja (story, tugas, ulasan, …)
owner	owner sahaja	tetapan projek, pengurusan keahlian, kunci ejen, padam, import, log audit

Bukan ahli menerima 404 unfound_resource (bukan 403) pada laluan projek, jadi ID projek tidak boleh dibilang.

Endpoint pemerihal-diri

Kaedah	Laluan	Penerangan
GET	/openapi.json	Spesifikasi OpenAPI 3 langsung. Tidak disahkan.
GET	/docs	Swagger UI. Tidak disahkan.
GET	/meta	Identiti pemanggil (auth.kind/key_id/agent_id/project_id) + graf peralihan jenis-story. Disahkan (mana-mana kunci yang sah; bukan berskop-projek). Panggil ini dahulu.

Akaun / identiti

Ini bertindak pada pemanggil dan hanya memerlukan kunci yang sah (tiada peranan projek).

Kaedah	Laluan	Penerangan
POST	/auth/register	Daftar akaun baharu
POST	/auth/login	Daftar masuk, memulangkan token sesi
POST	/auth/logout	Daftar keluar
POST	/auth/forgot-password	Minta e-mel tetap-semula kata laluan
POST	/auth/reset-password	Gunakan token tetap semula untuk menetapkan kata laluan baharu
GET	/auth/verify-email	Sahkan alamat e-mel
POST	/auth/accept-invite/lookup	Selesaikan token jemputan → e-mel (tidak disahkan)
POST	/auth/accept-invite	Terima jemputan projek (selepas pengesahan)
GET	/me	Profil pengguna semasa
PUT	/me	Kemas kini profil
DELETE	/me	Padam akaun
PUT	/me/password	Tukar kata laluan
PUT	/me/settings	Kemas kini tetapan (tema, keutamaan pemberitahuan)
POST	/me/avatar	Muat naik avatar (multipart)
POST	/me/api-token/regenerate	Putar token API anda — membatalkan sesi/kunci sedia ada
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Urus kunci API pengguna (ea_user_)
GET	/me/activity	Aktiviti anda merentasi semua projek
GET	/me/data-export	Eksport-sendiri GDPR data anda
GET	/me/consent · POST /me/consent	Baca / rekod persetujuan ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Dokumen clickwrap tertangguh / rekod penerimaan
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Hubungi + maklum balas dalam-aplikasi

Rujukan data (tidak disahkan)

Carian benih digunakan semasa mencipta/menganggar story. ID stabil.

Kaedah	Laluan	Penerangan
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	skala anggaran yang tersedia
GET	/effort_scales/{scale_id}/values	nilai mata dalam skala

Projek

Kaedah	Laluan	Penerangan
GET	/projects	Senaraikan projek anda
POST	/projects	Cipta projek
GET	/projects/{id}	Dapatkan butiran projek (viewer)
PUT	/projects/{id}	Kemas kini tetapan projek (owner)
DELETE	/projects/{id}	Padam projek (owner)
GET	/projects/{id}/audit-log	Aliran aktiviti projek (owner)
GET	/projects/{id}/events	Aliran peristiwa berhalaman-kursor (viewer) — lihat Peristiwa

Ahli dan kunci ejen

Kaedah	Laluan	Penerangan
GET	/projects/{id}/memberships	Senaraikan ahli (viewer)
POST	/projects/{id}/memberships	Jemput ahli melalui e-mel (owner)
PUT	/projects/{id}/memberships/{mid}	Kemas kini peranan (owner)
DELETE	/projects/{id}/memberships/{mid}	Keluarkan ahli (owner)
GET / POST	/projects/{id}/agent_keys	Senaraikan / cetak kunci ejen (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Batalkan kunci ejen (owner)

Story

Semua penulisan story memerlukan peranan member.

Kaedah	Laluan	Penerangan
GET	/projects/{id}/stories	Senaraikan story (berhalaman, boleh ditapis) (viewer)
POST	/projects/{id}/stories	Cipta story
GET	/projects/{id}/stories/{sid}	Dapatkan satu story (viewer)
PUT	/projects/{id}/stories/{sid}	Kemas kini story
DELETE	/projects/{id}/stories/{sid}	Padam story
POST	/projects/{id}/stories/{sid}/transitions	Tukar keadaan dengan pengesahan
POST	/projects/{id}/stories/bulk_transition	Ubah banyak story (1–100) sekaligus
POST	/projects/{id}/stories/bulk-delete	Padam banyak story
POST	/projects/{id}/stories/bulk-duplicate	Pendua banyak story
POST	/projects/{id}/stories/{sid}/duplicate	Pendua satu story

Cipta (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels menerima ["auth"] atau [{ "name": "auth" }]; label tidak diketahui dicipta. Lalai: story_type=feature, current_state=unstarted.

Kemas kini (PUT …/stories/{sid}): medan yang sama, semua pilihan, ditambah "position" (float) dan "force_state_change" (bool).

Peralihan (POST …/transitions): { "to": "<state>", "reason"? }. Medan ialah to. Memulangkan { story_id, state }. Gerakan tidak sah → 422 invalid_transition dengan details: { from, to, allowed }.

Peralihan pukal (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Setiap story dihakimi secara bebas; memulangkan { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Sub-sumber story

Semua member. Senarai/GET pada kebanyakannya ialah (viewer).

Kaedah	Laluan	Badan / nota
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (or task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (or 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? } — tinggalkan kedua-duanya untuk menambah 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}	muat naik multipart (≤ 2 GB setiap satu); senarai ialah (viewer)

Label

member untuk penulisan, (viewer) untuk bacaan.

Kaedah	Laluan	Penerangan
GET / POST	/projects/{id}/labels	Senaraikan / cipta label
PUT / DELETE	/projects/{id}/labels/{lid}	Kemas kini / padam label
POST	/projects/{id}/labels/{lid}/archive	Arkib (sembunyi-lembut) label

Iterasi

Kaedah	Laluan	Penerangan
GET	/projects/{id}/iterations	Senaraikan iterasi (member)
POST	/projects/{id}/iterations	Cipta iterasi manual (owner)
DELETE	/projects/{id}/iterations/{itid}	Padam iterasi (owner)

Carian, analitik, metrik, keutamaan

Kaedah	Laluan	Penerangan
GET	/projects/{id}/search?query=…	Carian sintaks penapis (viewer) — lihat Panduan
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analitik (viewer). Penelitian iterasi mengambil ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Metrik (viewer)
GET / PUT	/projects/{id}/preferences	Keutamaan papan anda untuk projek ini (member)

Peristiwa

Kaedah	Laluan	Penerangan
GET	/projects/{id}/events	Aliran peristiwa berhalaman-kursor (viewer)

Parameter pertanyaan: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Respons termasuk next_cursor. Hantar event_id terakhir yang anda lihat sebagai since untuk menyambung.

Import (owner)

Kaedah	Laluan	Penerangan
POST	/projects/{id}/import (+ /json)	Muat naik multipart. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

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

Untuk kawalan-jauh UI interaktif ({ "action": "get_state", "id": "req-1" }). Bukan saluran data — semua bacaan/penulisan melalui REST. Satu-instance sahaja; tidak disebarkan merentasi replika.

Idempotensi

Endpoint penulisan (POST, PUT, DELETE) menerima pengepala Idempotency-Key. Kunci yang sama + badan yang sama memainkan semula respons tercache (tetingkap 24 jam); kunci yang sama + badan yang berbeza memulangkan 409 idempotency_conflict. Tidak digunakan pada laluan GET/HEAD/OPTIONS, /auth/*, atau /attachments. Respons 5xx tidak pernah dicache — cuba semula mencapai pengendali.

Penghalamanan

Endpoint senarai menerima cursor=<opaque> dan limit=<n≤200>. Apabila ditetapkan, respons ialah { "items": [...], "next_cursor": "<str|null>" }; hantar next_cursor kembali untuk menghalamankan. Sesetengah senarai juga memulangkan pengepala X-Tracker-Pagination-Total.

Unjuran medan

Endpoint senarai menerima fields= (dipisahkan koma) untuk memulangkan hanya medan tertentu. story_id sentiasa disertakan; nama medan tidak diketahui memulangkan 400 validation_failed dengan nama yang menyalahi dalam details.fields.

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

Format ralat

Setiap ralat JSON mempunyai code dan error; sesetengahnya menambah details:

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

Status	code	Bila
400	invalid_parameter	input buruk; mesej dalam error, tiada details (kebanyakan pengesahan: kosong/panjang/null-byte/e-mel)
400	validation_failed	ralat input berstruktur; details.fields ialah tatasusunan nama medan yang menyalahi
401	unauthenticated	token hilang/tidak sah
403	unauthorized_operation	disahkan tetapi peranan tidak mencukupi
404	unfound_resource	tidak ditemui — juga dipulangkan kepada bukan ahli
409	conflict	konflik sumber (cth. pendua)
409	idempotency_conflict	Idempotency-Key diguna semula dengan badan yang berbeza
422	invalid_transition	gerakan keadaan tidak sah; details membawa { from, to, allowed }
500	internal_error	kesalahan pelayan — mesej generik; selamat untuk cuba semula

details.fields ialah tatasusunan JSON nama medan (cth. ["to"]), kadangkala dengan kunci tambahan seperti max. Tiada peta medan→mesej.

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

Had kadar

Setiap kunci (setiap IP untuk endpoint tidak disahkan), baldi token GCRA:

• Auth — /auth/*: 0.5 req/s, ledakan 20.
• Awam — /contact, /feedback: 0.2 req/s, ledakan 10.
• Sensitif — tetap-semula kata laluan: ~0.002 req/s, ledakan 5.

Had yang melebihi memulangkan 429 Too Many Requests dengan pengepala Retry-After dan badan teks-biasa (bukan sampul ralat JSON).