מפרט API

סימוכין מלא לנקודות הקצה של REST. למדריכים ולדוגמאות, ראו את מדריך API.

כל מה שחבר בפרויקט יכול לעשות בממשק האינטרנט זמין כאן — ה-SPA צורך את אותו ה-API הזה. פעולות הדורשות את תפקיד ה-manager מסומנות ב-(manager); כל השאר דורש רק חברוּת בפרויקט (או, עבור קריאות המסומנות ב-(viewer), כל רמת גישה). הטבלאות להלן מציינות כל קבוצת נתיבים שהשרת מתקין; אלה שמסוכמות בשורה אחת מתוארות במלואן ב-openapi.json החי.

בסיס

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 מגיש את אותו ה-API בדיוק. כל הבקשות והתגובות הן JSON, מלבד כמה נקודות קצה של העלאת-קבצים שמקבלות multipart.

שתי קבוצות יושבות רמה אחת למעלה, תחת /api ולא תחת /api/v1: משטח האימות (/api/auth/*) והטפסים הציבוריים (/api/contact, /api/feedback). הכתיבים שלהם בצורת /api/v1/… מחזירים 404.

אימות

כל בקשה מאומתת שולחת אישור גישה באמצעות אחד מ:

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

מפתחות משתמש מתחילים ב-ea_user_, מפתחות סוכן ב-ea_agent_, ואסימוני גישה של MCP ב-ea_mcp_. ראו מדריך API ← שלושה סוגי אישורי גישה.

נקודות קצה ללא אימות: /openapi.json, /docs, נקודות הקצה /api/auth/*, וחיפושי נתוני-הסימוכין (/story_types, /story_states, /effort_scales, /priority_scales). /meta הוא מאומת — כל מפתח תקף עובד, אך הוא אינו בהיקף פרויקט (מפתח סוכן הקשור לפרויקט מגיע אליו גם הוא).

תפקידים

ארבע רמות מהוות שער לנקודות קצה בהיקף פרויקט:

רמה	מי עובר	פעולות טיפוסיות
public viewer	כל אחד, בפרויקט שהנראות שלו ציבורית	קריאות של הלוח: סיפורים, איטרציות, חיפוש, פעילות סיפורים ואפיקים (עם השחרת פרטי המבצע)
viewer	viewer, member, manager	קריאות (רשימה/קבלת סיפורים, חיפוש, מדדים, רשימת פורמטי הייצוא)
member	member, manager	כל כתיבות פריטי-העבודה (סיפורים, מטלות, תגובות, …), זרם האירועים
manager	manager בלבד	הגדרות פרויקט, ניהול חברוּת, מפתחות סוכן, מחיקה, ייבוא, הורדות ייצוא, גיבויים, יומן ביקורת

לסוכנים יש אותם תפקידים כמו לחברים — viewer, member, או manager — עם תקרה בגובה התפקיד של החבר שטבע את המפתח. לא-חבר מקבל 404 unfound_resource (לא 403) בנתיבי פרויקט פרטיים, כך שמזהי פרויקט אינם ניתנים למניין.

נקודות קצה מתארות-עצמן

שיטה	נתיב	תיאור
GET	/openapi.json	מפרט OpenAPI 3 החי, כולל גופי הבקשה. ללא אימות.
GET	/docs	Swagger UI. ללא אימות.
GET	/meta	זהות הקורא (auth.kind/key_id/agent_id/project_id) + גרף המעברים לכל-סוג-סיפור. מאומת (כל מפתח תקף; לא בהיקף פרויקט). קראו לזה תחילה.
GET	/api/health · /api/config	בדיקת חיוּת, והתצורה הציבורית של הפריסה (מצב ארגון יחיד, אילו תכונות אופציונליות פעילות, שם המופע). ללא אימות, מחוץ ל-/v1.

נתיבי אימות (/api/auth/*, מחוץ ל-/v1)

נקודות קצה של מפגש, ללא אימות אלא אם צוין אחרת. ה-SPA מפעיל אותן; סקריפטים משתמשים בדרך כלל במפתח API במקומן.

שיטה	נתיב	תיאור
POST	/auth/register	רישום חשבון חדש — מוגן ב-reCAPTCHA; לאחר מכן החשבון עובר את אתגר ה-SMS
POST	/auth/sms/challenge · /auth/sms/status · /auth/sms/bypass	שליחה / בדיקה של קוד ה-SMS של ההרשמה (העקיפה מוגבלת למפעיל)
GET	/auth/config	אילו שיטות התחברות הפריסה מציעה
POST	/auth/login	התחברות עם דוא”ל + סיסמה; מחזיר JWT של מפגש, או אתגר TOTP
POST	/auth/login/totp	השלמת התחברות עם קוד מאפליקציית מאמת או קוד שחזור
POST	/auth/passkey/login/start · /auth/passkey/login/finish	התחברות WebAuthn ללא סיסמה
GET	/auth/oauth/github/start · /auth/oauth/github/callback · /auth/oauth/google/start · /auth/oauth/google/callback · POST /auth/oauth/exchange	התחברות OAuth עם GitHub או Google
POST	/auth/refresh · /auth/refresh/revoke	סבב של ה-refresh token / ביטולו
POST	/auth/logout	התנתקות (מבטלת את ה-refresh token)
POST	/auth/forgot-password · /auth/reset-password	בקשת דוא”ל לאיפוס / שימוש באסימון האיפוס
POST	/auth/accept-invite/lookup · /auth/accept-invite	פתרון אסימון הזמנה → דוא”ל / קבלת ההזמנה לפרויקט (לאחר אימות)

חשבון / זהות

אלה פועלים על הקורא ודורשים רק מפתח תקף (ללא תפקיד פרויקט).

שיטה	נתיב	תיאור
GET	/me	פרופיל המשתמש הנוכחי
PUT	/me	עדכון פרופיל
DELETE	/me	מחיקת חשבון — נדחית כל עוד אתם הבעלים היחידים של ארגון או של פרויקט עם חברים אחרים
GET	/me/deletion-impact	מה מחיקת החשבון תסיר ומה חוסם אותה
PUT	/me/password	שינוי סיסמה
PUT	/me/settings	עדכון הגדרות (ערכת נושא, העדפות התראות)
POST	/me/avatar	העלאת אווטר (multipart)
POST	/me/api-token/regenerate	סבב של אסימון ה-API שלכם — מבטל מפגשים/מפתחות קיימים
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	ניהול מפתחות API של משתמש (ea_user_)
GET	/me/totp · POST /me/totp/setup · /me/totp/verify · /me/totp/disable	הרשמה לאימות דו-שלבי (TOTP); verify מחזיר את קודי השחזור פעם אחת
GET	/me/passkeys · POST /me/passkeys/register/start · /me/passkeys/register/finish · DELETE /me/passkeys/{credential_id}	רישום והסרה של מפתחות גישה
GET	/me/oauth_grants · DELETE /me/oauth_grants/{grant_id}	אפליקציות מחוברות — לקוחות ה-MCP ואפליקציות ה-OAuth שאישרתם
GET	/me/activity	הפעילות שלכם בכל הפרויקטים
GET	/me/stories	סיפורים שבבעלותכם, שביקשתם, או שאתם עוקבים אחריהם בכל פרויקט שהאסימון מגיע אליו — role=owned|requested|following, state=, cursor= / limit= (מקסימום 200)
GET	/me/mentions · POST /me/mentions/{mention_id}/ack	תיבת ה-@-אזכורים (unacked=true לסינון) ואישור קבלה — מוזגה גם לפיד ההתראות להלן
GET	/me/data-export	ייצוא-עצמי של הנתונים שלכם לפי GDPR
GET	/me/consent · POST /me/consent	קריאה / רישום הסכמה ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	מסמכי clickwrap ממתינים / רישום קבלה
GET / PUT	/agent/me	הזהות והפרופיל של מפתח סוכן, שהסוכן יכול לקרוא ולערוך (המקבילה בצד הסוכן ל-/me)
POST	/api/contact · /api/feedback · /api/feedback/with-screenshot	יצירת קשר + משוב בתוך האפליקציה. מחוץ ל-/v1; מוגבל קצב לכל IP

נתוני סימוכין (ללא אימות)

חיפושי seed המשמשים ביצירת/הערכת סיפורים. מזהים יציבים.

שיטה	נתיב	תיאור
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	סולמות הערכה זמינים
GET	/effort_scales/{scale_id}/values	ערכי הנקודות בסולם
GET	/priority_scales · /priority_scales/{scale_id}/values	סולמות העדיפות והערכים שלהם (priority_id על סיפור נפתר כאן)

ארגונים

שירות מתארח בלבד — התקנה באירוח עצמי רצה במצב ארגון יחיד ואינה מתקינה את אלה (מלבד רשימת הארגונים). התפקידים הם תפקידי ארגון: owner, admin, member.

שיטה	נתיב	תיאור
GET / POST	/organizations	רשימת הארגונים שלכם / יצירת ארגון
GET / PUT / DELETE	/organizations/{oid}	קריאה, שינוי שם (שם + slug; בעלים או אדמין), מחיקה
GET / POST	/organizations/{oid}/memberships · PUT / DELETE …/memberships/{member_id}	חברים והזמנות; להזמנות יש תקרת תפקיד (לעולם לא מעל זה של הקורא; לתפקיד הבעלים אין מזמינים לעולם)
POST	/organizations/{oid}/memberships/bulk-role · …/memberships/bulk-remove	שינוי התפקיד של עד 200 חברים בבת אחת או הסרתם. הכול או כלום: אצווה שתסיר את ה-owner האחרון או תשאיר פרויקט ללא בעלים נדחית כולה; עם reassign_confirmed אתם הופכים לבעלים של הפרויקטים האלה במקום זאת
DELETE	/organizations/{oid}/invitations/{invitation_id}	ביטול הזמנה ממתינה
POST	/organizations/{oid}/transfer-ownership	העברת תפקיד הבעלים לחבר אחר
PUT	/organizations/{oid}/memberships/{member_id}/anonymization	מיסוך השם / הדוא”ל / האווטר של חבר בכל הארגון
GET	/organization-invitations/{token} · POST …/{token}/accept	פתרון / קבלה של הזמנה לארגון שנשלחה בדוא”ל
POST	/organizations/{oid}/export · GET / POST …/export/jobs · GET …/export/jobs/{job_id} · …/export/jobs/{job_id}/download	ייצוא ארגון לבעלים בלבד: zip עם dump של SQL וכל קובץ מצורף, שרץ כמשימה

פרויקטים

שיטה	נתיב	תיאור
GET	/projects	רשימת הפרויקטים שלכם (limit ≤ 200)
POST	/projects	יצירת פרויקט
GET	/projects/{id}	קבלת פרטי פרויקט (viewer)
PUT	/projects/{id}	עדכון הגדרות פרויקט (manager)
DELETE	/projects/{id}	מחיקת פרויקט (manager)
POST	/projects/{id}/pin	הצמדה / ביטול הצמדה של הפרויקט ברשימת הפרויקטים שלכם
POST	/projects/{id}/transfer-organization	העברת הפרויקט לארגון אחר (manager)
POST	/projects/{id}/slack/test	שליחת הודעת בדיקה להזנת ה-Slack של הפרויקט (manager)
GET / POST	/projects/{id}/showcase_claim_eligibility · /projects/{id}/showcase_claim · /projects/{id}/showcase_seed	פרויקטי תצוגה ציבוריים: בדיקה אם אפשר לתבוע אחד, תביעתו, אכלוסו
GET	/projects/{id}/audit-log	קריאת יומן הביקורת — היסטוריית הפרויקט וכן פעילות לפי סיפור / לפי epic דרך surface=; הגישה משתנה לפי ה-surface, ראו למטה
GET	/projects/{id}/events	זרם אירועים מדופדף-cursor (member) — ראו אירועים

פרמטרי שאילתה של יומן הביקורת: event_type= (סוג יחיד או רשימה מופרדת בפסיקים), limit= (≤ 1000), before= (סמן keyset, created_at בפורמט ISO-8601), surface= (project_history, story_activities, epic_activities), target_id= (מזהה הסיפור/ה-epic — נדרש כאשר surface=story_activities או epic_activities). גישה: היומן הלא מסונן ו-surface=project_history הם (manager); את story_activities / epic_activities יכול לקרוא כל חבר בפרויקט, ובפרויקטים ציבוריים גם באופן אנונימי עם השחרת פרטים מזהים של המבצע.

חברים, סוכנים ומפתחות סוכן

שיטה	נתיב	תיאור
GET	/projects/{id}/memberships	רשימת חברים (viewer)
POST	/projects/{id}/memberships	הזמנת חבר בדוא”ל (manager)
PUT	/projects/{id}/memberships/{mid}	עדכון תפקיד (manager)
DELETE	/projects/{id}/memberships/{mid}	הסרת חבר (manager)
GET	/projects/{id}/addable-members · POST /projects/{id}/members/add-existing	חברי ארגון שעדיין אינם בפרויקט / הוספת אחד מהם ללא הזמנה בדוא”ל (manager)
POST	/projects/{id}/members/join	בעלים או אדמין של ארגון מצטרפים לפרויקט בארגון שלהם כ-manager, או מקדמים את עצמם לתפקיד זה (הפעולה Make me owner ברשימת הפרויקטים)
PUT	/projects/{id}/members/{mid}/anonymization	מיסוך השם / הדוא”ל / האווטר של חבר בפרויקט זה (manager)
GET / POST	/projects/{id}/agent_keys	רשימה / טביעת מפתחות סוכן — מנהלים, או התפקידים שמדיניות תפקידי היוצרים של הפרויקט מתירה
DELETE	/projects/{id}/agent_keys/{kid}	ביטול מפתח סוכן
GET	/projects/{id}/agent_keys/onboarding	חבילת ה-onboarding: פרומפטים וקובצי תצורה עבור לקוחות הסוכנים הנפוצים
GET	/projects/{id}/agents · GET / PUT /projects/{id}/agents/{aid}	הסוכנים של הפרויקט והפרופילים שלהם (שם, ראשי תיבות, תיאור, צבע)
POST	/projects/{id}/agents/{aid}/rotate-key · /projects/{id}/agents/{aid}/avatar	סבב של מפתח סוכן (הזהות וההיסטוריה נשמרות) / העלאת האווטר שלו

סיפורים

כל כתיבות הסיפור דורשות את תפקיד ה-member.

שיטה	נתיב	תיאור
GET	/projects/{id}/stories	רשימת סיפורים (מדופדף, ניתן לסינון) (viewer)
POST	/projects/{id}/stories	יצירת סיפור
GET	/projects/{id}/stories/{sid}	קבלת סיפור אחד (viewer)
PUT	/projects/{id}/stories/{sid}	עדכון סיפור
DELETE	/projects/{id}/stories/{sid}	מחיקת סיפור
POST	/projects/{id}/stories/{sid}/transitions	שינוי מצב עם אימות
POST	/projects/{id}/stories/{sid}/reject · /projects/{id}/stories/{sid}/restart	דחיית סיפור שסופק / החזרת סיפור שנדחה ל-started (rejected הוא מצב סופי עבור /transitions)
POST	/projects/{id}/stories/{sid}/archive · /projects/{id}/stories/{sid}/unarchive	ארכוב / ביטול ארכוב של סיפור אחד
POST	/projects/{id}/stories/bulk_transition	מעבר של סיפורים רבים (1–100) בבת אחת
POST	/projects/{id}/stories/bulk-archive · bulk-delete · bulk-duplicate · bulk-move	ארכוב, מחיקה, שכפול, או העברה (לפאנל / מיקום) של סיפורים רבים
POST	/projects/{id}/stories/{sid}/duplicate	שכפול סיפור אחד
GET / POST / DELETE	/projects/{id}/stories/{sid}/epics · …/epics/{eid}	השתייכות הסיפור לאפיקים
GET	/short-links/{code} · /story-references	פתרון קישור מקוצר /s/<code> לסיפור שלו / פתרון של עד 100 הפניות לסיפורים (#id, כתובות URL) לסיפורים שהקורא יכול לקרוא

פרמטרי שאילתה של רשימת הסיפורים: archived= (exclude ברירת מחדל / include / only — מסנן הארכוב התלת-מצבי; מחליף את include_archived=true שהוצא משימוש, המשמש כעת ככינוי ל-archived=include), include_done=true (מכניס סיפורים מפאנל Done הקפואים על איטרציות עבר, המוחרגים כברירת מחדל). דפדוף (cursor= / limit= / offset=) וקבוצות שדות חלקיות (fields=) פועלים לפי דפדוף והקרנת שדות.

יצירה (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. estimate הוא התווית של ערך הסולם כמחרוזת ("3", "13"); מספר JSON נדחה. labels מקבל ["auth"] או [{ "name": "auth" }]; תוויות לא-מוכרות נוצרות. ברירות מחדל: story_type=feature, current_state=unstarted.

עדכון (PUT …/stories/{sid}): אותם שדות, כולם אופציונליים, בתוספת "position" (float), "force_state_change" (bool), ו-"expected_updated_at" (RFC 3339 — שמירת תיאור נדחית עם 409 stale_write אם הסיפור השתנה מאז שקראתם אותו). כתיבות סיפור מכבדות גם If-Match מול ה-ETag של הסיפור; אי-התאמה היא 412 precondition_failed.

מעבר (POST …/transitions): { "to": "<state>" }. השדה הוא to. מחזיר { story_id, state }. תנועה לא-חוקית → 422 invalid_transition עם details: { from, to, allowed }.

מעבר קבוצתי (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>" }. כל סיפור נשפט באופן עצמאי; מחזיר { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

תת-משאבים של סיפור

כולם member. רשימה/GET על רובם הוא (viewer).

שיטה	נתיב	גוף / הערות
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) } או { comment_emoji }. GET מקבל fields= (רשימת ההיתר: comment_id, story_comment_id, story_id, comment_text, comment_emoji, member, created) בתוספת 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; כתובות GitHub מסוג /pull/ ו-/tree/ מסווגות אוטומטית
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	יצירה: { reviewer_id? / reviewer_agent_id?, comment? } — השמיטו את שניהם כדי להקצות את עצמכם. עדכון: { status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — השמיטו את שניהם כדי להוסיף את הקורא
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}	העלאת multipart — וידאו ≤ 200 MB, PDF / Word / Excel ≤ 25 MB, תמונות / CSV / טקסט ≤ 10 MB; רשימה היא (viewer)
GET / POST	/projects/{id}/stories/{sid}/link-attachments · DELETE …/link-attachments/{laid}	קבצים מצורפים מסוג קישור — URL חיצוני שנשמר לצד הקבצים המצורפים ולא כקישור קוד
GET	/attachments/{token} · /api/avatars/{token}	קריאות של קובץ מצורף או אווטר לפי אסימון — הכתובות שה-API מחלק; אין צורך ב-X-TrackerToken

אפיקים

אותו מבנה כמו סיפורים, בלי מכונת המצבים. member לכתיבות, (viewer) לקריאות.

שיטה	נתיב	תיאור
GET / POST	/projects/{id}/epics · GET / PUT / DELETE …/epics/{eid}	לאפיקים יש שם, תיאור ב-Markdown, ותווית תומכת שמחברת את הסיפורים שלהם
GET / POST / PUT / DELETE	…/epics/{eid}/comments · …/comments/{cid}	תגובות על אפיקים
GET / POST / DELETE	…/epics/{eid}/owners · …/followers (+ גרסאות /agents/{aid})	בעלים ועוקבים, חברים או סוכנים — הבעלים של אפיק מתפשטים לסיפורים שלו
GET / POST / DELETE	…/epics/{eid}/attachments (+ /json) · …/link-attachments	קבצים מצורפים, באותן מגבלות כמו לסיפורים
GET	/projects/{id}/analytics/epics · …/analytics/epics/{eid}	התקדמות לכל אפיק: burnup, תפוקה, בריאות, תחזית (viewer)

תוויות

member לכתיבות, (viewer) לקריאות.

שיטה	נתיב	תיאור
GET / POST	/projects/{id}/labels	רשימה / יצירת תווית
PUT / DELETE	/projects/{id}/labels/{lid}	עדכון / מחיקת תווית
POST	/projects/{id}/labels/{lid}/archive	ארכוב (הסתרה רכה) של תווית

איטרציות

הקריאות פתוחות לכל תפקיד בפרויקט, וגם באופן אנונימי בפרויקט ציבורי.

שיטה	נתיב	תיאור
GET	/projects/{id}/iterations	רשימת איטרציות (≤ 500 לעמוד; נושאת ETag ואת כותרות ההמשך X-Tracker-Pagination-* כשהיא מקוצצת)
GET	/projects/{id}/iterations/{itid}	איטרציה אחת
GET	/projects/{id}/iterations/first-preview	התאריכים שהאיטרציה הראשונה תקבל, המוצגים באישור היצירה
POST	/projects/{id}/iterations	יצירת איטרציה ידנית (member)
DELETE	/projects/{id}/iterations/{itid}	מחיקת איטרציה (manager)
PUT	/projects/{id}/iterations/{itid}/velocity	עקיפת המהירות של איטרציה אחת בלי לשנות את האסטרטגיה של הפרויקט (manager)
GET	/projects/{id}/iterations/{itid}/done-stories	הסיפורים שהתקבלו באיטרציה סגורה, מדופדפים

חיפוש, מדדים, העדפות

שיטה	נתיב	תיאור
GET	/projects/{id}/search?q=…	חיפוש רב-עוצמה — טקסט מלא + מגדירי היבט / טווח תאריכים / אנשים (DSL בסגנון GitHub); מחזיר { results, total, limit, offset }. query הוא כינוי ל-q; limit= (ברירת מחדל 50, מקסימום 1000) / offset= מדפדפים; sort= ממיין לפי relevance (ברירת מחדל), created, created_asc, state, או updated. (viewer) — ראו את המדריך
GET	/projects/{id}/metrics/{velocity,burndown,story-types,contributors}	הסדרות של עמוד ה-Metrics (viewer); מדדי האפיקים נמצאים תחת /analytics/epics לעיל
GET	/projects/{id}/backlog/grouping	קבוצות האיטרציות המוקרנות של ה-Backlog (viewer)
GET / PUT	/projects/{id}/preferences	העדפות הלוח שלכם לפרויקט זה — כל תפקיד בפרויקט, השורה שלכם בלבד

אירועים

שיטה	נתיב	תיאור
GET	/projects/{id}/events	זרם אירועים מדופדף-cursor (member) — viewers מקבלים 403

פרמטרי שאילתה: since=<event_id>, types=story.created,story.transitioned,comment.added,…, limit= (≤ 500), cursor=. התגובה כוללת next_cursor. העבירו את ה-event_id האחרון שראיתם כ-since כדי להמשיך.

התראות

פיד ההתראות המאוחד בתוך האפליקציה: שורות התראה מן המניין (בקשות סקירה, פעילות בסיפורים, הזמנות ועוד) ממוזגות עם תיבת ה-@-אזכורים לזרם אחד, מהחדש לישן. מזהי הפיד נושאים קידומת מקור (nt-… / sc-… / ec-…). מפגשים של חברים ומפתחות ea_user_* קוראים את שורות צד-החבר שלהם; מפתחות ea_agent_* את שורות צד-הסוכן.

שיטה	נתיב	תיאור
GET	/me/notifications	פיד ההתראות שלכם. מסננים: unread=true, since_id=, kind= (mentions / reviews / stories / invitations); דפדוף באמצעות cursor= / limit=
GET	/me/notifications/unread-count	סיכומי לא-נקראו — { unread_count, by_category: { mentions, reviews, stories, invitations } }
POST	/me/notifications/read-all	סימון הכול כנקרא; מחזיר את המונים המעודכנים
POST	/me/notifications/{id}/ack	סימון פריט אחד כנקרא (אידמפוטנטי)
POST	/me/notifications/{id}/accept	קבלת הזמנה לפרויקט / ארגון ישירות מהפיד (אסימוני חבר בלבד)
POST	/me/notifications/{id}/decline	דחיית הזמנה לפרויקט / ארגון (אסימוני חבר בלבד)
GET	/me/notifications/resolve-invite?token=…	המרת אסימון הזמנה שנשלח בדוא”ל למזהה ההתראה שלכם — { "id": "nt-…" } או { "id": null }
GET	/me/notifications/stream	דחיפה חיה — Server-Sent Events (text/event-stream); ראו בהמשך

נקודת הקצה של הזרם אינה נקודת קצה JSON ולכן אינה במפרט ה-OpenAPI: היא משאירה את החיבור פתוח ופולטת מסגרת ללא payload ({"type":"notification","kind":…}) בכל פעם שמשהו חדש מגיע, כאות ללקוח לרענן את הפיד. חיבורים נסגרים בצד השרת אחרי 45 דקות — התחברו ואמתו מחדש. מפגשים של חברים ומפתחות ea_user_* בלבד; מפתחות ea_agent_* מקבלים 403.

ייבוא (manager)

שיטה	נתיב	תיאור
POST	/projects/{id}/import	מקורות-קבצים: source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat. file= multipart. סינכרוני — עונה עם ספירות התוצאה.
POST	/projects/{id}/import/json	גוף JSON; source=github אינו צריך קובץ — owner, repo, token אופציונלי, ודגלי ההצטרפות מרצון include_pull_requests / include_milestones / include_releases / include_dependencies; מקורות הקבצים שולחים file_base64. אסינכרוני: מחזיר 202 { import_id, status }. השרת שולף דרך ה-GraphQL API של GitHub, שדוחה קוראים אנונימיים, ולכן תמיד מגיע אסימון ל-GitHub — שלכם, או המשותף של הפריסה. ראו את המדריך.
GET	/projects/{id}/imports/{import_id}	poll למשימה: status עובר pending → fetching → writing → done | failed, עם progress_current / progress_total בזמן השליפה וספירות התוצאה ב-done

רק ייבוא אחד רץ לכל פרויקט בכל רגע; POST שני בזמן שאחד בעיצומו הוא 409 import_already_running. dry_run: true (גוף JSON או dry_run=true multipart) מציג תצוגה מקדימה של כל מקור: מפרסר, פותר, מסיר כפילויות, מחזיר את אותן הספירות { imported, skipped, errors, unmatched }, ואז מגלגל לאחור — דבר אינו נכתב. תקרות: גוף 10 MiB, ו-5,000 סיפורים לכל ייבוא עבור מקורות הקבצים (חריגה מאחת מהן → 400, ללא כתיבה). למקור GitHub אין תקרה — הוא כותב במנות ולא בטרנזקציה אחת. ייבוא חוזר אידמפוטנטי לכל מזהה מקור — שורות שכבר יובאו מדולגות, לא משוכפלות.

ייצוא

שיטה	נתיב	תיאור
GET	/projects/{id}/export/formats	פורמטים רשומים: { id, name, content_type, drops, includes_archived }. כל תפקיד בפרויקט.
GET	/projects/{id}/export/{format}	הורדת אחד (manager). חילופין: eat (נאמנות מלאה), jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json; מסמכים: pdf, docx.
GET	/projects/{id}/export/attachments	כל קובץ מצורף כ-zip יחיד הניתן לעיון (קבצים שומרים על שמותיהם המקוריים; מניפסט JSON + CSV) (manager).

ייצוא מסמכים (pdf, docx) מקבל פרמטרי שאילתה נוספים: page_size= (letter ברירת מחדל / a4 / legal / folio), from= / to= (גבולות חלון-הסיפורים — RFC 3339 או YYYY-MM-DD פשוט; סיפור נמצא בטווח כאשר ה-created או ה-completed_at שלו נופל בתוכו), include_icebox= / include_backlog= (שניהם false כברירת מחדל, כך שייצוא הניתן לשיתוף מציג רק עבודה מתוזמנת / בעיצומה). פורמטי ה-CSV לחילופין מתעלמים מהם.

גיבויים ושחזורים (manager)

שיטה	נתיב	תיאור
GET / POST	/projects/{id}/backups · GET …/backups/{snapshot_id} · …/backups/health	רשימת תמונות מצב, צילום אחת עכשיו, קריאת אחת, וסיכום בריאות השמירה
GET / POST	/projects/{id}/restores · POST …/restores/partial · GET …/restores/{restore_id}	שחזור תמונת מצב שלמה, או טבלאות נבחרות ממנה, ו-poll לשחזור

בקשות ה-POST יושבות בשכבת מגבלות הקצב הרגישה (להלן).

ספק MCP ו-OAuth

East Agile Tracker הוא ספק OAuth 2.1 עבור לקוחות MCP. לקוח מגלה אותו ב-/.well-known/oauth-authorization-server וב-/.well-known/oauth-protected-resource/mcp, שולח אתכם ל-/oauth/authorize (דף ההסכמה), מחליף את הקוד ב-/oauth/token, ואז מדבר MCP ב-/mcp עם אסימון ה-ea_mcp_* שהתקבל. ההרשאות מופיעות ומבוטלות ב-/me/oauth_grants. לנקודות הקצה של הספק יש שכבת מגבלות קצב משלהן.

WebSocket

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

לשליטה מרחוק אינטראקטיבית בממשק המשתמש ({ "action": "get_state", "id": "req-1" }). האסימון הוא JWT של מפגש דפדפן — מפתח API נדחה עם 401 לפני השדרוג. אינו ערוץ נתונים — כל הקריאות/הכתיבות עוברות דרך REST. מופע יחיד בלבד; אינו מתפרס על פני רפליקות.

אידמפוטנטיות

נקודות קצה של כתיבה (POST, PUT, DELETE) מקבלות כותרת Idempotency-Key. אותו מפתח + אותו גוף משמיע מחדש את התגובה השמורה (חלון של 24 שעות); אותו מפתח + גוף שונה מחזיר 409 idempotency_conflict. המפתח תחום לאישור הגישה ששלח אותו. אינו חל על GET/HEAD/OPTIONS, על /openapi.json ו-/docs, על /api/auth/*, או על העלאות multipart בנתיבי /attachments. תגובות שנעצרו לפני תשובה של התחום לעולם אינן נשמרות — 401, 403, 404, 429, וכל 5xx — כך שניסיון חוזר אחרי כל אחת מהן מגיע ל-handler; 400, 409, 412, ו-422 הן התשובה של התחום ומושמעות מחדש כמו הצלחה.

דפדוף (Pagination)

נקודות קצה של רשימה מקבלות cursor=<opaque> ו-limit=<n>. כשהוגדרו, התגובה היא { "items": [...], "next_cursor": "<str|null>" }; העבירו את next_cursor בחזרה כדי לדפדף. תקרת ה-limit נקבעת לכל נקודת קצה: 200 בסיפורים, בתגובות ובפרויקטים; 500 באירועים; 1000 בחיפוש וביומן הביקורת.

רשימה רגילה (ללא cursor/limit) שנאלצה לקצץ את התגובה שלה מציינת זאת בכותרות — X-Tracker-Pagination-Truncated, X-Tracker-Pagination-Limit, X-Tracker-Pagination-Offset, ו-X-Tracker-Pagination-Next-Offset; העבירו את האחרונה בחזרה כ-offset= לעמוד הבא. אין כותרת של ספירה כוללת.

הקרנת שדות (Field projection)

נקודות קצה של רשימה מקבלות fields= (מופרד בפסיקים) כדי להחזיר רק שדות מסוימים. story_id תמיד נכלל; שם שדה לא-מוכר מחזיר 400 validation_failed עם השמות הפוגעים ב-details.fields.

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

פורמט שגיאה

לכל שגיאת JSON יש code ו-error; חלק מוסיפות details:

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

סטטוס	code	מתי
400	invalid_parameter	קלט שגוי; הודעה ב-error, ללא details (רוב האימות: ריק/אורך/null-byte/דוא”ל)
400	validation_failed	שגיאת קלט מובְנית; details.fields הוא מערך של שמות שדות פוגעים
401	unauthenticated	אסימון חסר/לא-תקף
403	unauthorized_operation	מאומת אך תפקיד לא-מספיק
404	unfound_resource	לא נמצא — מוחזר גם ללא-חברים
409	conflict	התנגשות משאב (למשל כפילות)
409	idempotency_conflict	Idempotency-Key נעשה בו שימוש חוזר עם גוף שונה
409	stale_write · import_already_running	הסיפור השתנה מאז ה-expected_updated_at שלכם · ייבוא כבר בעיצומו
412	precondition_failed	If-Match לא תאם את ה-ETag הנוכחי של המשאב; details נושא את expected ואת current
413	request_too_large	הגוף חורג ממגבלת הגודל של הנתיב
422	invalid_transition	תנועת מצב לא-חוקית; details נושא { from, to, allowed }
429	rate_limited	יותר מדי בקשות מה-IP הזה בנתיב מוגבל קצב; כותרת Retry-After
500	internal_error	תקלת שרת — הודעה כללית; בטוח לנסות שוב
503	not_configured	לפריסה חסרה האינטגרציה שהנתיב הזה צריך (SMS, אחסון אובייקטים, …)

details.fields הוא מערך JSON של שמות שדות (למשל ["to"]), לעיתים עם מפתחות נוספים כמו max. אין מפת שדה→הודעה.

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

מגבלות קצב

לכל IP של לקוח, בקומץ נתיבים; תעבורת API מאומתת בשאר המקומות אינה מוגבלת קצב. ברירות מחדל (כל זוג הוא קצב מתמשך ופרץ, ניתנים לכוונון על ידי המפעיל):

• Auth — /api/auth/*: 0.5 בקשות/שנייה, פרץ 20.
• ספק OAuth — /oauth/*: 1 בקשה/שנייה, פרץ 60.
• Public — /api/contact: 0.2 בקשות/שנייה, פרץ 10.
• משוב — /api/feedback: שלוש שכבות מוערמות — שליחה אחת כל 15 שניות, 10 בשעה, 36 ביום.
• אווטרים — ההפניה הלא מאומתת של אווטרים: 20 בקשות/שנייה, פרץ 200.
• רגיש — בקשות ה-POST של גיבוי ושחזור: ~0.002 בקשות/שנייה, פרץ 5.

מגבלה שנחרגה מחזירה 429 עם כותרת Retry-After ומעטפת שגיאת ה-JSON הסטנדרטית, code: "rate_limited".