מדריך API

ה-API של East Agile Tracker מעוצב לסוכנים לא פחות מאשר לבני אדם. כל מה שאתם יכולים לעשות בממשק המשתמש, אתם יכולים לעשות דרך ה-API — וכמה דברים שממשק המשתמש לא חושף נמצאים שם גם הם.

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

שלושה סוגי אישורי גישה

אתם מאמתים את עצמכם באמצעות מפתח בכותרת X-TrackerToken. יש שני סוגי מפתחות שאתם טובעים בעצמכם, וסוג שלישי שלקוח MCP משיג עבורכם:

מפתחות משתמש (ea_user_…) — פועלים כ-אתם. צרו אותם ב-Account Settings → API Keys. השתמשו בהם לסקריפטים אישיים, כלי CLI, אינטגרציות.
מפתחות סוכן (ea_agent_…) — פועלים כ-סוכן בעל שם בפרויקט אחד. צרו אותם ב-Project Settings → Agents. השתמשו בהם לסוכני בינה מלאכותית — Claude Code, Codex, שלכם — שאמורים להשתתף בפרויקט כחברי צוות בעלי שם.
אסימוני MCP (ea_mcp_…) — אסימוני גישה של OAuth 2.1 שמונפקים ללקוח MCP (Claude, סביבת פיתוח) אחרי שאישרתם אותו בדף ההסכמה. הם פועלים בשמכם, ואפשר לבטל אותם תחת Account Settings → Connected apps.

החלון החד-פעמי אחרי יצירת מפתח API אישי בהגדרות החשבון, והמפתח מוסתר בצילום הזה

טופס יצירת המפתח בלשונית Agent עם שם ותפקיד member שנבחר, מתחת להוראות ההגדרה

ההבדלים בין שני הסוגים שאתם טובעים:

	מפתח משתמש	מפתח סוכן
היקף	כל הפרויקטים שלכם	פרויקט אחד ספציפי
זהות בשובל הביקורת	שמכם	שם הסוכן
תפקיד	התפקיד שלכם בכל פרויקט	נקבע ביצירת המפתח (viewer, member, או manager — לעולם לא מעל התפקיד של החבר שטבע אותו)
ביטול	בטלו מפתח; אתם שומרים גישה דרך מפתחות/מפגשים אחרים	בטלו או סובבו מפתח; הסוכן מאבד גישה מיידית
הכי טוב עבור	אוטומציה אישית, סקריפטים	סוכני בינה מלאכותית שאמורים להיות ניתנים להבחנה מכם בהיסטוריה

Authorization: Bearer … עובד גם הוא אם אתם מעדיפים סגנון כותרת זה.

שלום, API

קבלו את הפרויקטים שלכם:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

או עבור מפתח סוכן, רשמו את הפרויקט שאליו הוא מוגדר:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

ה-API הוא JSON, REST- למחצה, בגרסה תחת /api/v1/. אותם מבנים לבני אדם ולסוכנים.

יצירת פרויקט

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

התגובה כוללת את project_id וכל ברירות המחדל שהשרת יישם (סולם הערכה, מצב סיום, וכו’).

יצירת סיפור

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate הוא התווית של ערך הסולם כמחרוזת — "3", או "13" בסולם Fibonacci — כי הוא חייב להתאים לנקודה בסולם של הפרויקט. מספר JSON נדחה.

העברת סיפור לאורך מחזור החיים

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

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

השדה הוא to (לא to_state). אם התנועה אינה חוקית — נניח ניסיתם לדלג מ-unstarted ישר ל-accepted — התגובה היא 422 invalid_transition עם פרטי שגיאה מובְנים:

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

זהו אחד מהדברים הקטנים שהופכים את ה-API לידידותי-לסוכנים: סוכן יכול לקרוא את details.allowed ולבחור את התנועה הבאה הנכונה ללא גרידת פרוזה.

rejected הוא מצב סופי מבחינת נקודת הקצה של המעבר. כדי להחזיר סיפור שנדחה לעבודה, קראו ל-POST …/stories/{sid}/restart; POST …/stories/{sid}/reject הוא צורת הפועל לדחיית סיפור שסופק.

תגובה על סיפור

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

התגובה מיוחסת למי שבבעלותו מפתח ה-API — אם זהו מפתח סוכן, מחבר התגובה הוא הסוכן.

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

כל נקודת קצה של כתיבה מקבלת כותרת Idempotency-Key. נסו שוב את אותו מפתח עם אותו גוף, קבלו בחזרה את אותה תגובה. נסו שוב את אותו מפתח עם גוף שונה, קבלו 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

זה קריטי לסוכנים בלולאות ניסיון-חוזר — קרסתם באמצע כתיבה, נסו שוב עם אותו מפתח, ללא סיפורים כפולים.

מעברים קבוצתיים

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

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

מעקב אחר זרם האירועים

עבור סוכנים שרוצים להגיב למה שבני אדם עושים, בצעו poll לנקודת הקצה של האירועים:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

התגובה היא זרם של אירועים עם דפדוף מבוסס-cursor, עם המבצע, המשאב, והשינוי. לכל אירוע יש מזהה; העבירו את המזהה האחרון שראיתם כ-since כדי להמשיך מהיכן שעצרתם. ללא webhooks, ללא גרידה, ללא אירועים שהוחמצו. הזרם דורש את תפקיד ה-member — viewer מקבל 403.

חיפוש

GET /projects/{id}/search?q=<query> מריץ חיפוש רב-עוצמה, טקסט מלא + מובנה, על פני הסיפורים של הפרויקט. שפת השאילתות בנויה על דגם מגדירי חיפוש ה-issues של GitHub — כך שתחביר שאתם (או סוכן בינה מלאכותית) כבר מכירים מ-GitHub עובר ברובו כמו שהוא.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

התגובה היא מעטפת JSON, עם סיפורים מדורגים לפי רלוונטיות:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total הוא מספר ההתאמות המלא, לא גודל העמוד. דפדפו עם limit (ברירת מחדל 50, מקסימום 1000) ו-offset; מיינו עם sort=relevance (ברירת מחדל), created, created_asc, updated, או state.

תחביר

טקסט חופשי מתאים לכותרת, למזהה ולתיאור של הסיפור (טקסט מלא, עם גזירת שורשים ודירוג). עטפו ביטוי מדויק ב-"quotes".
מגדירים הם field:value. הפרידו חלופות בפסיקים (OR בתוך שדה): type:bug,chore. הפרידו מגדירים ברווחים (AND ביניהם).
שללו כל מונח או מגדיר בעזרת - מוביל: -label:wontfix.
טווחים לתאריכים ולנקודות: כולל a..b, או פתוח בקצה אחד >x / <x.

מגדירים

מגדיר	דוגמה	מתאים ל
`type:`	`type:bug,chore`	סוג(י) סיפור
`state:`	`state:started,finished`	מצב(י) זרימת עבודה
`label:`	`label:"my label"`	תווית
`epic:`	`epic:"Checkout"`	סיפורים באפיק
`priority:`	`priority:p1`	עדיפות
`points:`	`points:3` · `points:1..5` · `points:>3`	ערך הערכה או טווח
`iteration:`	`iteration:42`	מזהה איטרציה
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	תאריך או טווח (ברזולוציית יום); `release:` הוא תאריך השחרור של הסיפור
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	אדם לפי שם או דוא”ל — חברים וגם סוכנים, כולל `mention:`; `@me` הוא אתם
`has:blocker`	`has:blocker`	יש לו חוסם פתוח
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	דגל

mywork: הוא כינוי ל-owner: — mywork:me הוא owner:@me. המגדיר הישן scheduled: הוצא משימוש ומתעלמים ממנו בשקט; השתמשו ב-release:.

OR בפסיקים (type:bug,chore) חל על מגדירי ההיבטים; מגדירי האנשים (owner: requester: follower: reviewer: commenter: mention:) מקבלים ערך יחיד.

דוגמאות

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

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

גילוי ה-API

מפרט OpenAPI 3 החי נמצא ב:

https://api.eastagiletracker.com/api/v1/openapi.json

Swagger UI נמצא ב:

https://api.eastagiletracker.com/api/v1/docs/

/openapi.json ו-/docs אינם דורשים אימות — סוכן יכול לקרוא את החוזה לפני שיש לו מפתח. ברגע שהוא מחזיק במפתח, /api/v1/meta (שדורש מפתח תקף) מחזיר את זהותו ואת גרף המעברים לכל-סוג-סיפור; חיפושי נתוני-הסימוכין (/story_types, /story_states, /effort_scales, /priority_scales) אף הם אינם דורשים אימות. יחד הם מאפשרים לסוכנים לענות על “מה אני יכול לעשות כאן?” ללא תשובות 403 של ניסוי-וטעייה.

ה-openapi.json המוגש נושא סכמות של גופי בקשה עבור נקודות הקצה של כתיבה, כולל ה-maxLength של כל שדה, כך שלקוח יכול לאמת לפני שהוא שולח. ה-מפרט מסכם את אותם מבנים.

בקרת WebSocket

עבור אוטומציה אינטראקטיבית — הפעלת מפגש דפדפן מחובר מתוך סקריפט, או שליטה מרחוק בממשק המשתמש למדריכים — קיים ערוץ WebSocket:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

ה-token הוא ה-JWT של מפגש הדפדפן, לא מפתח API — מפתח ea_user_* או ea_agent_* נדחה לפני השדרוג. רוב המשתמשים לעולם לא יזדקקו לזה; הוא קיים עבור המקרים שבהם REST אינו מספיק.

ייבוא מ-tracker אחר

אם אתם כותבים סקריפט להגירה קבוצתית:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

מקורות-קבצים נתמכים: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (פורמט הייצוא של East Agile Tracker עצמו — פורמט המסע הלוך-ושוב). נקודת הקצה של multipart רצה באופן סינכרוני ועונה עם ספירות התוצאה.

GitHub מייבא מה-API במקום מקובץ, דרך נקודת הקצה של JSON — ללא file, רק קואורדינטות המאגר:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

נקודת הקצה של JSON היא אסינכרונית: היא עונה 202 עם { "import_id", "status" } ואתם מבצעים poll ל-GET /projects/{id}/imports/{import_id} עד שהמשימה מגיעה ל-done או failed. רק ייבוא אחד רץ לכל פרויקט בכל רגע — קריאה שנייה בזמן שאחד בעיצומו מחזירה 409 import_already_running. הלולאה כולה, עם שדות ההתקדמות של המשימה, נמצאת באכלוס פרויקט ממאגר GitHub.

ה-token אופציונלי בבקשה, אך השליפה עצמה תמיד עוברת אימות — היא רצה על ה-GraphQL API של GitHub, שאין בו שכבה אנונימית. השמיטו את token והשרת ישתמש באסימון הפלטפורמה שלו: מאגרים ציבוריים בלבד, משותף לכל הקוראים, ונדחה עם import_github_shared_quota_low כשתקציב ה-GraphQL שלו יורד מתחת ל-500 נקודות. מאגר פרטי, או פריסה שלא הוגדר בה אסימון פלטפורמה (import_github_no_token), מחייבים את שלכם. יהיה האסימון אשר יהיה, הוא משמש רק עבור קריאות GitHub במעלה הזרם ולעולם אינו נשמר או מוחזר. הפירוט המלא, כולל תקרת ה-REST הלא מאומתת של 60 בקשות ב-GitHub, נמצא באכלוס פרויקט ממאגר GitHub.

תצוגה מקדימה של הרצה-יבשה. הוסיפו "dry_run": true (JSON) או -F "dry_run=true" (multipart) לכל מקור. הייבוא מפרסר, פותר, ומסיר כפילויות בדיוק כמו הרצה אמיתית, מחזיר את אותן ספירות התוצאה (imported, skipped, errors, unmatched), ואז מגלגל את הכול לאחור — דבר אינו נכתב. בנקודת הקצה של JSON הספירות מגיעות על המשימה שעליה מבצעים poll, בין אם זו הרצה יבשה ובין אם לא.

מגבלות. גוף העלאה מוגבל ל-10 MiB, וייבוא בודד ל-5,000 סיפורים; חריגה מאחת מהן היא 400 ללא כתיבה של דבר. ייבוא חוזר של קובץ בטוח — שורות שכבר יובאו (מותאמות לפי מזהה המקור) מדולגות, לא משוכפלות.

ייצוא פרויקט

כל תפקיד בפרויקט יכול לרשום את הפורמטים; הורדה של אחד מהם היא לבעלים בלבד:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

מזהי פורמטי חילופין: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, בתוספת פורמטי המסמך pdf ו-docx. כל קובץ מצורף ניתן להורדה כ-zip יחיד מ-GET /projects/{id}/export/attachments.

פורמט שגיאה

כל השגיאות הן JSON עם לכל הפחות:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

תגובות שגיאה רבות כוללות גם אובייקט details — details.fields (מערך של שמות שדות פוגעים) ב-validation_failed, ו-details.allowed (לצד from/to) ב-422 invalid_transition. השתמשו בהם. 429 rate_limited נושא כותרת Retry-After באותה מעטפת JSON.

דפדוף (Pagination)

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

מה הלאה

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