מדריך API

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

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

שני סוגי מפתחות

אתם מאמתים את עצמכם באמצעות מפתח API בכותרת X-TrackerToken. ישנם שני סוגים:

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

ההבדלים:

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

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"]
  }'

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

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

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 ולבחור את התנועה הבאה הנכונה ללא גרידת פרוזה.

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

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.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

חיפוש עם תחביר הסינון

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

מסננים זמינים:

מסנן	דוגמה	תיאור
type:	type:feature	סינון לפי סוג סיפור
state:	state:started	סינון לפי מצב
label:	label:"my label"	סינון לפי תווית
owner:	owner:claire	סינון לפי בעלים
requester:	requester:tomas	סינון לפי מבקש
has:	has:blocker	סיפורים עם חוסמים
is:	is:unestimated	תכונות לא-מוערכות

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

גילוי ה-API

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

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

Swagger UI נמצא ב:

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

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

הערה: ה-openapi.json המוגש מפרט נתיבים אך כרגע מגיע עם גופי בקשה ריקים — השתמשו במבני השדות ב-מפרט עבור כתיבות.

בקרת WebSocket

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

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

רוב המשתמשים לעולם לא יזדקקו לזה; הוא קיים עבור המקרים שבהם 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.

פורמט שגיאה

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

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

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

דפדוף (Pagination)

נקודות קצה של רשימה מקבלות limit ו-cursor. ה-cursor הוא אטום; העבירו את ה-next_cursor מהתגובה הקודמת. כותרות התגובה כוללות גם X-Tracker-Pagination-Total לספירות סך-הכול במקרים שזה זול לחישוב.

מה הלאה

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