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 manager ditandakan (manager); segala yang lain hanya memerlukan keahlian projek (atau, untuk bacaan yang ditandakan (viewer), mana-mana tahap akses). Jadual di bawah menamakan setiap kumpulan laluan yang dipasang oleh pelayan; kumpulan yang diringkaskan dalam satu baris diterangkan sepenuhnya dalam openapi.json langsung.

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.

Dua kumpulan berada satu tahap di atas, di bawah /api dan bukannya /api/v1: permukaan pengesahan (/api/auth/*) dan borang awam (/api/contact, /api/feedback). Ejaan /api/v1/… bagi kumpulan ini memulangkan 404.

Pengesahan

Setiap permintaan yang disahkan menghantar bukti kelayakan melalui salah satu daripada:

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

Kunci pengguna bermula dengan ea_user_, kunci ejen dengan ea_agent_, dan token akses MCP dengan ea_mcp_. Lihat Panduan API → Tiga jenis bukti kelayakan.

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

Peranan

Empat tahap mengawal endpoint berskop-projek:

Tahap	Siapa yang lulus	Operasi tipikal
public viewer	sesiapa sahaja, pada projek yang keterlihatannya awam	bacaan papan: story, iterasi, carian, aktiviti story dan epik (dengan butiran pelaku disunting keluar)
viewer	viewer, member, manager	bacaan (senarai/dapat story, carian, metrik, senarai format eksport)
member	member, manager	semua penulisan item-kerja (story, tugas, ulasan, …), aliran peristiwa
manager	manager sahaja	tetapan projek, pengurusan keahlian, kunci ejen, padam, import, muat turun eksport, sandaran, log audit

Ejen memegang peranan yang sama seperti ahli — viewer, member, atau manager — dihadkan pada peranan ahli yang mencetak kunci itu. Bukan ahli menerima 404 unfound_resource (bukan 403) pada laluan projek persendirian, jadi ID projek tidak boleh dibilang.

Endpoint pemerihal-diri

Kaedah	Laluan	Penerangan
GET	/openapi.json	Spesifikasi OpenAPI 3 langsung, termasuk badan permintaan. 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.
GET	/api/health · /api/config	Keaktifan, dan konfigurasi awam deployment (mod organisasi tunggal, ciri pilihan yang dihidupkan, nama instans). Tidak disahkan, di luar /v1.

Auth (/api/auth/*, di luar /v1)

Endpoint sesi, tidak disahkan melainkan dinyatakan. SPA memacu endpoint ini; skrip biasanya menggunakan kunci API sebaliknya.

Kaedah	Laluan	Penerangan
POST	/auth/register	Daftar akaun baharu — dilindungi reCAPTCHA; akaun kemudian melalui cabaran SMS
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	Hantar / semak kod SMS pendaftaran (bypass dikawal oleh pengendali)
GET	/auth/config	Kaedah daftar masuk yang ditawarkan oleh deployment
POST	/auth/login	Daftar masuk dengan e-mel + kata laluan; memulangkan JWT sesi, atau cabaran TOTP
POST	/auth/login/totp	Selesaikan daftar masuk dengan kod pengesah atau kod pemulihan
POST	/auth/passkey/login/start · /auth/passkey/login/finish	Daftar masuk WebAuthn tanpa kata laluan
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	Daftar masuk OAuth dengan GitHub atau Google
POST	/auth/refresh · /auth/refresh/revoke	Putar refresh token / batalkannya
POST	/auth/logout	Daftar keluar (membatalkan refresh token)
POST	/auth/forgot-password · /auth/reset-password	Minta e-mel tetapan semula / gunakan token tetapan semula
POST	/auth/accept-invite/lookup · /auth/accept-invite	Selesaikan token jemputan → e-mel / terima jemputan projek (selepas pengesahan)

Akaun / identiti

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

Kaedah	Laluan	Penerangan
GET	/me	Profil pengguna semasa
PUT	/me	Kemas kini profil
DELETE	/me	Padam akaun — ditolak selagi anda satu-satunya pemilik organisasi atau projek yang mempunyai ahli lain
GET	/me/deletion-impact	Apa yang akan dikeluarkan oleh pemadaman akaun dan apa yang menghalangnya
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/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	Pendaftaran dua faktor (TOTP); verify memulangkan kod pemulihan sekali sahaja
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	Pendaftaran dan pembuangan passkey
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	Aplikasi bersambung — klien MCP dan aplikasi OAuth yang telah anda benarkan
GET	/me/activity	Aktiviti anda merentasi semua projek
GET	/me/stories	Story yang anda miliki, minta, atau ikuti merentasi setiap projek yang boleh dicapai oleh token — role=owned|requested|following, state=, cursor= / limit= (maksimum 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	Peti masuk @-sebutan (unacked=true untuk menapis) dan pengakuan — juga digabungkan ke dalam suapan pemberitahuan di bawah
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
GET / PUT	/agent/me	Identiti dan profil kunci ejen itu sendiri, boleh dibaca dan disunting oleh ejen (rakan pihak-ejen bagi /me)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	Hubungi + maklum balas dalam-aplikasi. Di luar /v1; had kadar setiap IP

Data rujukan (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
GET	/priority_scales · /priority_scales/{scale_id}/values	skala keutamaan dan nilainya (priority_id pada story diselesaikan di sini)

Organisasi

Perkhidmatan yang dihos sahaja — pemasangan hos sendiri berjalan dalam mod organisasi tunggal dan tidak memasang laluan ini (kecuali senarai organisasi). Peranan ialah peranan organisasi: owner, admin, member.

Kaedah	Laluan	Penerangan
GET / POST	/organizations	Senaraikan organisasi anda / cipta satu
GET / PUT / DELETE	/organizations/{oid}	Baca, namakan semula (nama + slug; pemilik atau admin), padam
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	Ahli dan jemputan; jemputan membawa siling peranan (tidak pernah melebihi peranan pemanggil; owner tidak pernah dijemput)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	Tukar peranan atau alih keluar sehingga 200 ahli sekali gus. Semua atau tiada: kelompok yang akan mengalih keluar owner terakhir atau meninggalkan projek tanpa pemilik ditolak sepenuhnya; dengan reassign_confirmed anda menjadi pemilik projek tersebut
DELETE	/organizations/{oid}/invitations/{invitation_id}	Batalkan jemputan tertangguh
POST	/organizations/{oid}/transfer-ownership	Serahkan peranan pemilik kepada ahli lain
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	Sembunyikan nama / e-mel / avatar ahli di seluruh organisasi
GET	/organization-invitations/{token} · POST …/{token}/accept	Selesaikan / terima jemputan organisasi yang dihantar melalui e-mel
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	Eksport organisasi untuk pemilik sahaja: zip dengan longgokan SQL dan setiap lampiran, dijalankan sebagai kerja

Projek

Kaedah	Laluan	Penerangan
GET	/projects	Senaraikan projek anda (limit ≤ 200)
POST	/projects	Cipta projek
GET	/projects/{id}	Dapatkan butiran projek (viewer)
PUT	/projects/{id}	Kemas kini tetapan projek (manager)
DELETE	/projects/{id}	Padam projek (manager)
POST	/projects/{id}/pin	Semat / nyahsemat projek pada senarai projek anda
POST	/projects/{id}/transfer-organization	Pindahkan projek ke organisasi lain (manager)
POST	/projects/{id}/slack/test	Hantar mesej ujian ke suapan Slack projek (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	Projek pameran awam: semak sama ada anda boleh menuntutnya, tuntutnya, benihkannya
GET	/projects/{id}/audit-log	Bacaan log audit — sejarah projek serta aktiviti setiap-story / setiap-epik melalui surface=; akses berbeza mengikut surface, lihat di bawah
GET	/projects/{id}/events	Aliran peristiwa berhalaman-kursor (member) — lihat Peristiwa

Parameter pertanyaan log audit: event_type= (satu jenis atau senarai dipisah koma), limit= (≤ 1000), before= (kursor keyset, created_at ISO-8601), surface= (project_history, story_activities, epic_activities), target_id= (id story/epik — wajib apabila surface=story_activities atau epic_activities). Akses: log tanpa tapisan dan surface=project_history ialah (manager); story_activities / epic_activities boleh dibaca oleh mana-mana ahli projek, dan secara tanpa nama pada projek awam dengan PII pelaku disunting keluar.

Ahli, ejen, dan kunci ejen

Kaedah	Laluan	Penerangan
GET	/projects/{id}/memberships	Senaraikan ahli (viewer)
POST	/projects/{id}/memberships	Jemput ahli melalui e-mel (manager)
PUT	/projects/{id}/memberships/{mid}	Kemas kini peranan (manager)
DELETE	/projects/{id}/memberships/{mid}	Keluarkan ahli (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	Ahli organisasi yang belum berada dalam projek / tambah seorang tanpa jemputan e-mel (manager)
POST	/projects/{id}/members/join	Pemilik atau admin organisasi menyertai projek dalam organisasinya sebagai manager, atau menaikkan diri sendiri menjadi manager (tindakan Make me owner pada senarai projek)
PUT	/projects/{id}/members/{mid}/anonymization	Sembunyikan nama / e-mel / avatar ahli pada projek ini (manager)
GET / POST	/projects/{id}/agent_keys	Senaraikan / cetak kunci ejen — pengurus, atau peranan yang dibenarkan oleh dasar peranan pencipta projek
DELETE	/projects/{id}/agent_keys/{kid}	Batalkan kunci ejen
GET	/projects/{id}/agent_keys/onboarding	Pakej orientasi: gesaan dan fail konfigurasi untuk klien ejen yang biasa
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	Ejen projek dan profil mereka (nama, inisial, penerangan, warna)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	Putar kunci ejen (identiti dan sejarah dikekalkan) / muat naik avatarnya

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/{sid}/reject · /projects/{id}/stories/{sid}/restart	Tolak story yang delivered / kembalikan story yang ditolak ke started (rejected adalah terminal bagi /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	Arkib / nyaharkib satu story
POST	/projects/{id}/stories/bulk_transition	Ubah banyak story (1–100) sekaligus
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	Arkib, padam, pendua, atau pindah (ke panel / kedudukan) banyak story
POST	/projects/{id}/stories/{sid}/duplicate	Pendua satu story
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	Keahlian epik story
GET	/short-links/{code} · /story-references	Selesaikan pautan pendek /s/<code> kepada story-nya / selesaikan sehingga 100 rujukan story (#id, URL) kepada story yang boleh dibaca pemanggil

Parameter pertanyaan senarai story: archived= (exclude lalai / include / only — penapis arkib tiga-keadaan; menggantikan include_archived=true yang telah lapuk, kini alias untuk archived=include), include_done=true (memasukkan story panel Done yang dibekukan pada iterasi lepas, dikecualikan secara lalai). Penghalamanan (cursor= / limit= / offset=) dan set medan jarang (fields=) mengikut Penghalamanan dan Unjuran medan.

Cipta (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate ialah label nilai skala sebagai rentetan ("3", "13"); nombor JSON ditolak. 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), "force_state_change" (bool), dan "expected_updated_at" (RFC 3339 — simpanan penerangan ditolak dengan 409 stale_write jika story telah berubah sejak anda membacanya). Penulisan story juga mematuhi If-Match terhadap ETag story; ketidakpadanan ialah 412 precondition_failed.

Peralihan (POST …/transitions): { "to": "<state>" }. 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>" }. 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 mengambil fields= (senarai dibenarkan: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) serta cursor= / limit= (≤ 200) / order=asc|desc
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · PUT/DELETE …/links/{lid}	{ url, link_type?, title? } — link_type ∈ relates_to, duplicates, blocks, is_blocked_by, pull_request, branch, other; URL GitHub /pull/ dan /tree/ diberi jenis secara automatik
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	Cipta: { reviewer_id? / reviewer_agent_id?, comment? } — tinggalkan kedua-duanya untuk menugaskan diri anda. Kemas kini: { 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 — video ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, imej / CSV / teks ≤ 10 MB; senarai ialah (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	Lampiran pautan — URL luar yang disimpan bersama lampiran fail dan bukannya sebagai pautan kod
GET	/attachments/{token} · /api/avatars/{token}	Bacaan beralamat-token bagi lampiran atau avatar — URL yang diberikan oleh API; tiada X-TrackerToken diperlukan

Epik

Bentuk yang sama seperti story, tanpa mesin keadaan. member untuk penulisan, (viewer) untuk bacaan.

Kaedah	Laluan	Penerangan
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	Epik membawa nama, penerangan Markdown, dan label sandaran yang menghimpunkan story-nya
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	Ulasan epik
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ varian /agents/{aid})	Pemilik dan pengikut, ahli atau ejen — pemilik epik diwarisi oleh story-nya
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	Lampiran, had yang sama seperti story
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	Kemajuan setiap epik: burnup, daya pemprosesan, kesihatan, ramalan (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

Bacaan terbuka kepada mana-mana peranan projek, dan tanpa nama pada projek awam.

Kaedah	Laluan	Penerangan
GET	/projects/{id}/iterations	Senaraikan iterasi (≤ 500 setiap halaman; membawa ETag dan pengepala sambungan X-Tracker-Pagination-* apabila dipotong)
GET	/projects/{id}/iterations/{itid}	Satu iterasi
GET	/projects/{id}/iterations/first-preview	Tarikh yang akan diberikan kepada iterasi pertama, ditunjukkan dalam pengesahan pembenihan
POST	/projects/{id}/iterations	Cipta iterasi manual (member)
DELETE	/projects/{id}/iterations/{itid}	Padam iterasi (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	Atasi velocity satu iterasi tanpa menukar strategi projek (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	Story yang diterima bagi iterasi yang ditutup, berhalaman

Carian, metrik, keutamaan

Kaedah	Laluan	Penerangan
GET	/projects/{id}/search?q=…	Carian berkuasa — teks penuh + kelayakan faset / julat tarikh / orang (DSL gaya GitHub); memulangkan { results, total, limit, offset }. query ialah alias bagi q; limit= (lalai 50, maksimum 1000) / offset= untuk penghalamanan; sort= menyusun mengikut relevance (lalai), created, created_asc, state, atau updated. (viewer) — lihat Panduan
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	Siri data halaman Metrics (viewer); metrik epik berada di bawah /analytics/epics di atas
GET	/projects/{id}/backlog/grouping	Kumpulan iterasi yang diunjurkan oleh Backlog (viewer)
GET / PUT	/projects/{id}/preferences	Keutamaan papan anda untuk projek ini — mana-mana peranan projek, baris anda sendiri sahaja

Peristiwa

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

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

Pemberitahuan

Suapan pemberitahuan bersepadu dalam aplikasi: baris pemberitahuan kelas pertama (permintaan semakan, aktiviti story, jemputan, …) digabungkan dengan peti masuk @-sebutan menjadi satu aliran, terbaharu dahulu. Id suapan berawalan sumber (nt-… / sc-… / ec-…). Sesi ahli dan kunci ea_user_* membaca baris pihak-ahli mereka; kunci ea_agent_* baris pihak-ejennya.

Kaedah	Laluan	Penerangan
GET	/me/notifications	Suapan pemberitahuan anda. Penapis: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); halaman melalui cursor= / limit=
GET	/me/notifications/unread-count	Jumlah belum dibaca — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	Tandakan semua sebagai dibaca; memulangkan kiraan terkini
POST	/me/notifications/{id}/ack	Tandakan satu item sebagai dibaca (idempoten)
POST	/me/notifications/{id}/accept	Terima jemputan projek / organisasi terus daripada suapan (token ahli sahaja)
POST	/me/notifications/{id}/decline	Tolak jemputan projek / organisasi (token ahli sahaja)
GET	/me/notifications/resolve-invite?token=…	Padankan token jemputan yang dihantar melalui e-mel dengan id pemberitahuan anda — { "id": "nt-…" } atau { "id": null }
GET	/me/notifications/stream	Push langsung — Server-Sent Events (text/event-stream); lihat di bawah

Endpoint stream bukan endpoint JSON dan oleh itu tiada dalam spesifikasi OpenAPI: ia mengekalkan sambungan terbuka dan memancarkan bingkai tanpa payload ({"type":"notification","kind":…}) setiap kali sesuatu yang baharu tiba, memberitahu klien supaya mengambil semula suapan. Sambungan ditamatkan di pihak pelayan selepas 45 minit — sambung semula dan sahkan semula. Sesi ahli dan kunci ea_user_* sahaja; kunci ea_agent_* menerima 403.

Import (manager)

Kaedah	Laluan	Penerangan
POST	/projects/{id}/import	Sumber fail: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. Multipart file=. Segerak — menjawab dengan kiraan hasil.
POST	/projects/{id}/import/json	Badan JSON; source=github tidak memerlukan fail — owner, repo, token pilihan, dan bendera pilih-masuk include_pull_requests / include_milestones / include_releases / include_dependencies; sumber fail menghantar file_base64. Tak segerak: memulangkan 202 { import_id, status }. Pelayan mengambil melalui API GraphQL GitHub, yang menolak pemanggil tanpa nama, jadi sebuah token sentiasa sampai ke GitHub — milik anda, atau token kongsi deployment. Lihat Panduan.
GET	/projects/{id}/imports/{import_id}	Tinjau kerja: status bergerak pending → fetching → writing → done | failed, dengan progress_current / progress_total semasa pengambilan dan kiraan hasil pada done

Satu import berjalan bagi setiap projek pada satu masa; POST kedua semasa satu sedang berjalan ialah 409 import_already_running. dry_run: true (badan JSON atau multipart dry_run=true) mempratonton mana-mana sumber: menghurai, menyelesaikan, menyahduplikasi, menghasilkan kiraan { imported, skipped, errors, unmatched } yang sama, kemudian mengundur — tiada apa yang ditulis. Had: badan 10 MiB dan 5,000 story setiap import bagi sumber berasaskan fail (melebihi salah satu → 400, tiada apa ditulis). Sumber GitHub tiada siling — ia menulis secara berkelompok dan bukan dalam satu transaksi. Import semula adalah idempoten mengikut id sumber — baris yang telah diimport dilangkau, bukan diduplikasi.

Eksport

Kaedah	Laluan	Penerangan
GET	/projects/{id}/export/formats	Format berdaftar: { id, name, content_type, drops, includes_archived }. Mana-mana peranan projek.
GET	/projects/{id}/export/{format}	Muat turun satu (manager). Pertukaran: eat (kesetiaan penuh), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; dokumen: pdf, docx.
GET	/projects/{id}/export/attachments	Setiap lampiran sebagai satu zip boleh-layar (fail mengekalkan nama asal; manifes JSON + CSV) (manager).

Eksport dokumen (pdf, docx) mengambil parameter pertanyaan tambahan: page_size= (letter lalai / a4 / legal / folio), from= / to= (sempadan tetingkap story — RFC 3339 atau YYYY-MM-DD sahaja; story berada dalam julat apabila created atau completed_at-nya jatuh di dalamnya), include_icebox= / include_backlog= (kedua-duanya lalai false, jadi eksport boleh-kongsi hanya menunjukkan kerja terjadual / sedang berjalan). Format CSV pertukaran mengabaikannya.

Sandaran dan pemulihan (manager)

Kaedah	Laluan	Penerangan
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	Senaraikan snapshot, ambil satu sekarang, baca satu, dan ringkasan kesihatan pengekalan
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	Pulihkan keseluruhan snapshot, atau jadual terpilih daripadanya, dan tinjau pemulihan

POST itu berada pada peringkat had kadar sensitif (di bawah).

MCP dan penyedia OAuth

East Agile Tracker ialah penyedia OAuth 2.1 untuk klien MCP. Klien menemuinya di /.well-known/oauth-authorization-server dan /.well-known/oauth-protected-resource/mcp, menghantar anda ke /oauth/authorize (halaman persetujuan), menukar kod di /oauth/token, dan kemudian bercakap MCP di /mcp dengan token ea_mcp_* yang terhasil. Geran disenaraikan dan dibatalkan di /me/oauth_grants. Endpoint penyedia mempunyai peringkat had kadar tersendiri.

WebSocket

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

Untuk kawalan-jauh UI interaktif ({ "action": "get_state", "id": "req-1" }). Token ialah JWT sesi pelayar — kunci API ditolak dengan 401 sebelum naik taraf sambungan. 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. Kunci diskopkan kepada bukti kelayakan yang menghantarnya. Tidak digunakan pada GET/HEAD/OPTIONS, /openapi.json dan /docs, /api/auth/*, atau muat naik multipart pada laluan /attachments. Respons yang terhenti sebelum jawapan domain tidak pernah dicache — 401, 403, 404, 429, dan setiap 5xx — jadi cuba semula selepas mana-mana daripadanya mencapai pengendali; 400, 409, 412, dan 422 ialah jawapan domain dan dimainkan semula seperti kejayaan.

Penghalamanan

Endpoint senarai menerima cursor=<opaque> dan limit=<n>. Apabila ditetapkan, respons ialah { "items": [...], "next_cursor": "<str|null>" }; hantar next_cursor kembali untuk menghalamankan. Had limit berbeza bagi setiap endpoint: 200 pada story, ulasan, dan projek; 500 pada peristiwa; 1000 pada carian dan log audit.

Senarai biasa (tanpa cursor/limit) yang terpaksa memotong responsnya menyatakannya dalam pengepala — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, dan X-Tracker-Pagination-Next-Offset; hantar yang terakhir kembali sebagai offset= untuk halaman seterusnya. Tiada pengepala jumlah kiraan.

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
409	stale_write · import_already_running	story telah berubah sejak expected_updated_at anda · import sudah sedang berjalan
412	precondition_failed	If-Match tidak sepadan dengan ETag semasa sumber; details membawa expected dan current
413	request_too_large	badan melebihi had saiz laluan
422	invalid_transition	gerakan keadaan tidak sah; details membawa { from, to, allowed }
429	rate_limited	terlalu banyak permintaan daripada IP ini pada laluan yang dihadkan kadarnya; pengepala Retry-After
500	internal_error	kesalahan pelayan — mesej generik; selamat untuk cuba semula
503	not_configured	deployment tidak mempunyai integrasi yang diperlukan oleh laluan ini (SMS, storan objek, …)

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 IP klien, pada segelintir laluan; trafik API yang disahkan di tempat lain tidak dihadkan kadarnya. Lalai (setiap pasangan ialah kadar berterusan dan ledakan, boleh dilaraskan oleh pengendali):

• Auth — /api/auth/*: 0.5 req/s, ledakan 20.
• Penyedia OAuth — /oauth/*: 1 req/s, ledakan 60.
• Awam — /api/contact: 0.2 req/s, ledakan 10.
• Maklum balas — /api/feedback: tiga peringkat bertindan — satu penghantaran setiap 15 s, 10 sejam, 36 sehari.
• Avatar — ubah hala avatar yang tidak disahkan: 20 req/s, ledakan 200.
• Sensitif — POST sandaran dan pemulihan: ~0.002 req/s, ledakan 5.

Had yang dilampaui memulangkan 429 dengan pengepala Retry-After dan sampul ralat JSON standard, code: "rate_limited".