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://api.eastagiletracker.com/api/v1

API mempunyai hosnya sendiri: eastagiletracker.com menghidangkan aplikasi web dan menjawab /api/v1/… dengan 404. 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 hubungan awam (/api/contact). 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 (disahkan; membatalkan refresh token sesi ini)
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)
POST	/auth/oauth/link/preview · …/link/confirm · /auth/oauth/merge/preview · …/merge/confirm	Sambungkan akaun GitHub atau Google kepada akaun sedia ada, atau gabungkan dua akaun
POST	/auth/email_addresses/primary/preview · …/primary/confirm	Selesaikan perubahan e-mel utama daripada pautan pengesahan yang dihantar melalui e-mel

Akaun / identiti

Ini bertindak pada pemanggil dan tidak memerlukan peranan projek. Ia memerlukan identiti ahli — kunci ejen mendapat 401 (ejen menggunakan /agent/me). Panggilan yang mengubah bukti kelayakan — kata laluan, TOTP, passkey, pemadaman akaun, perubahan e-mel, penjanaan semula token — memerlukan sesi pelayar; kunci API mendapat 403.

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 / DELETE	/me/avatar	Muat naik (multipart) / buang avatar anda
POST	/me/api-token/regenerate	Log keluar setiap sesi dan pulangkan token sesi baharu; kunci API tidak terjejas
GET / POST	/me/email_addresses · GET …/email_addresses/offers · PUT …/email_addresses/primary	Alamat e-mel anda; gunakan alamat penyedia yang disambungkan sebagai alamat alternatif; minta perubahan e-mel utama (disahkan melalui e-mel)
GET	/me/oauth_identities · DELETE …/oauth_identities/{provider} · POST …/oauth_identities/{provider}/link	Akaun log masuk yang disambungkan (GitHub, Google): senaraikan, putuskan sambungan, mulakan pautan
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/v1/feedback · /api/v1/feedback/with-screenshot	Hubungi + maklum balas dalam-aplikasi; 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
GET	/organization-invitations/{token} · POST …/{token}/accept	Selesaikan / terima jemputan organisasi yang dihantar melalui e-mel
GET	/organizations/{oid}/export · 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 / DELETE	/projects/{id}/pin	Semat / nyahsemat projek pada senarai projek anda
POST	/projects/{id}/transfer-organization	Pindahkan projek ke organisasi lain — pemanggil mestilah Pengurus projek dan pemilik atau pentadbir organisasi sasaran
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 (penyemaian adalah untuk pentadbir produk; orang lain mendapat 404)
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= (lalai 50, dihadkan kepada 1000), before= (kursor keyset <ISO-8601>|<audit_id> — hantar next_cursor halaman sebelumnya), surface= (project_history, story_activities, epic_activities), target_id= (id story/epik — wajib apabila surface=story_activities atau epic_activities). Akses: log tanpa tapisan ialah (manager); surface=project_history ialah (viewer), dengan e-mel ahli disunting keluar apabila projek menyembunyikannya; 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)
POST	/projects/{id}/memberships/bulk-role · …/memberships/bulk-remove	Tukar peranan, atau buang, ramai ahli sekaligus (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) dan pemilik atau pentadbir organisasi
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)
GET / POST	/projects/{id}/agent_keys	Senaraikan (manager) / cetak kunci ejen — orang yang peranannya berada dalam dasar peranan pencipta projek; kunci ejen tidak boleh mencetak
PUT / DELETE	/projects/{id}/agent_keys/{kid}	Sunting nama, peranan atau petunjuk respons kunci / batalkannya (manager)
GET	/projects/{id}/agent_keys/onboarding	Pakej orientasi: gesaan dan fail konfigurasi untuk klien ejen yang biasa
GET	/projects/{id}/agents · GET / PUT / DELETE /projects/{id}/agents/{aid}	Ejen projek dan profil mereka (nama, inisial, penerangan, warna); DELETE membatalkan ejen dan semua kuncinya — pengurus atau pencipta ejen
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. Mencipta story dengan tarikh terdahulu, asal-usul import (import_source / import_external_id), atau pemilik atau peminta luaran memerlukan (manager).

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-unarchive	Nyaharkib banyak 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
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 — codes= (kod pautan pendek dipisah koma) dan ids= (project_id:story_id dipisah koma) — 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_version" (integer, version story — simpanan penerangan ditolak dengan 409 stale_write jika penerangan telah berubah selepas versi tersebut). "expected_updated_at" (RFC 3339) yang lebih lama sudah lapuk dan masih berfungsi untuk satu keluaran lagi: jika dihantar bersama penerangan dan tanpa expected_version, simpanan ditolak dengan 409 stale_write melainkan nilainya sama dengan updated_at story. 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). Memadam lampiran atau lampiran pautan memerlukan pemuat naiknya atau (manager).

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}	Cipta: { url, link_type?, title? }; kemas kini: { url, 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}	{ label_id } — label projek sedia ada; cipta label dengan POST /projects/{id}/labels, atau hantar labels pada PUT story
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/v1/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 dan untuk senarai ulasan, pemilik dan pengikut; (viewer) untuk senarai epik, satu epik, dan senarai lampiran.

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
GET / PUT / DELETE	/projects/{id}/labels/{lid}	Baca / 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	Tetingkap masa, velocity yang diunjurkan dan pengisian Backlog bagi iterasi yang akan dicipta oleh tulisan penyemaian, atau bagi iterasi semasa jika ia wujud (member)
POST	/projects/{id}/iterations	Cipta iterasi manual (manager)
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_id=<event_id> (since ialah alias lama; since_id diutamakan apabila kedua-duanya dihantar), types=story.created,story.transitioned,comment.added,…, limit= (lalai 100, ≤ 500), cursor=. Respons ialah { items, next_since_id, next_cursor }: simpan next_since_id dan hantar semula sebagai since_id untuk menyambung; next_cursor ialah null pada halaman terakhir.

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, dan include_comments (lalai true); 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 JSON berjalan bagi setiap projek pada satu masa; POST …/import/json kedua semasa satu sedang berjalan ialah 409 import_already_running. Dengan check_unpointed_estimates: true (sumber fail; diabaikan untuk github), fail yang mengandungi anggaran pepijat atau tugasan yang tidak diberi mata oleh projek ditolak dengan 409 import_unpointed_estimates dan details.count sebelum sebarang job bermula; tanpa bendera itu, import membuang anggaran tersebut dan melaporkan { code: "estimates_unpointed_dropped", count } dalam warnings keputusan. 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: fail 10 MiB (400 import_too_large) dan 5,000 story setiap import bagi sumber berasaskan fail (400 import_too_many_records); tiada apa yang ditulis. Badan permintaan melebihi 16 MiB ditolak lebih awal dengan 413 request_too_large. 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
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.

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/*, /mcp, mana-mana laluan yang mengandungi /attachments, atau mana-mana permintaan multipart/*; permintaan tanpa bukti kelayakan tidak pernah dicache. 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 log audit. Carian menghalamankan dengan limit (≤ 1000) dan offset dan bukannya kursor, dan memulangkan { results, total, limit, offset }.

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

Senarai story, ulasan, dan projek menerima fields= (dipisahkan koma) untuk memulangkan hanya medan tertentu. Id sumber sentiasa disertakan (story_id, story_comment_id dan comment_id, project_id); 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. Pengesahan medan (kosong/panjang/null-byte/e-mel) menambah details.fields dan details.constraint; hanya ralat permintaan buruk biasa yang tiada details
400	validation_failed	ralat input berstruktur; details.fields ialah tatasusunan nama medan yang menyalahi
400	kod domain	penolakan khusus laluan dengan kodnya sendiri dan tanpa details — cth. unsupported_export_format, import_too_large, import_unknown_source
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 · import_unpointed_estimates	penerangan telah berubah selepas expected_version anda (atau expected_updated_at tidak lagi sepadan) · import sudah sedang berjalan · fail mengandungi anggaran pepijat atau tugasan yang tidak diberi mata oleh projek (details.count)
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
502	upstream_error	perkhidmatan yang diperlukan oleh laluan (cth. GitHub) gagal
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/v1/feedback dan /api/v1/feedback/with-screenshot: 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".