# ממשק REST API של שַׁגֵּר בעשר דקות: מהקריאה whoami ועד פוסט מתוזמן לעשרות חשבונות

_2026-09-15 · מדריך מהיר לממשק REST API של שַׁגֵּר: אימות Bearer, מבנה תשובות ושגיאות, מגבלת קצב, ורצף קריאות אמיתי מסביבת עבודה, דרך העלאת מדיה וטיוטה, ועד תזמון ואנליטיקס._

ממשק REST API של שַׁגֵּר יושב תחת `https://app.shager.ai/api/v1`, מאמת כל בקשה בכותרת `Authorization: Bearer shgr_live_…`, ומחזיר תשובות במבנה `{ "data": … }` ושגיאות במבנה `{ "error": { "code", "message" } }`. הרצף הבסיסי הוא `GET /me`, אחריו `GET /workspaces`, רשימת החשבונות של סביבת עבודה, העלאת מדיה, יצירת פוסט ותזמון שלו. המפרט המלא, OpenAPI 3.1, נמצא בכתובת [https://app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json), וכל פעולה בו מקבילה לכלי באותו שם בשרת MCP.

המדריך מיועד למפתחים שבונים אוטומציה, אינטגרציה או סוכן משלהם, ומעדיפים קוד על פני שרת MCP. הדוגמאות כתובות בכלי curl כדי שיהיה קל להעתיק, אבל כל שפה שיודעת לשלוח HTTP תעבוד. טיפ קטן לפני שמתחילים: טענו את קובץ OpenAPI לכלי שאתם עובדים איתו לבדיקת API, או תנו אותו לסוכן הקוד שלכם. כל שדה מתועד בו עם תיאור, מגבלות אורך וערכים מותרים, וזה חוסך ניחושים לגבי מה בדיוק כל נתיב מצפה לקבל.

## לפני הקריאה הראשונה

צריך מפתח API. אדם בצוות יוצר אותו בכתובת `https://app.shager.ai/dashboard/agents` ובוחר הרשאות מתוך `read`, `write` או `publish`, או שסוכן נרשם בעצמו ומקבל sandbox, כמו שמוסבר במדריך [על הרשמה עצמית של סוכן](/blog/agent-self-signup-and-claim). הגישה לממשק API כלולה בכל המסלולים, כולל החינמי, כפי שמופיע ב[עמוד המחירים](/pricing).

שומרים את המפתח במשתנה סביבה:

```bash
export SHAGER_API_KEY="shgr_live_XXXXXXXXXXXXXXXX"
export SHAGER="https://app.shager.ai/api/v1"
```

## מפת הפעולות

| פעולה | שיטה ונתיב | הרשאה סבירה |
|---|---|---|
| whoami | `GET /me` | read |
| list_workspaces | `GET /workspaces` | read |
| create_workspace | `POST /workspaces` | write |
| list_channels | `GET /workspaces/{id}/channels` | read |
| create_connect_link | `POST /workspaces/{id}/connect-links` | write |
| list_groups, create_group | `GET` או `POST /workspaces/{id}/groups` | read, write |
| upload_media_from_url | `POST /workspaces/{id}/media` | write |
| create_post, list_posts | `POST` או `GET /workspaces/{id}/posts` | write, read |
| get_post | `GET /workspaces/{id}/posts/{post_id}` | read |
| schedule_post | `POST /workspaces/{id}/posts/{post_id}/schedule` | publish |
| request_approval | `POST /workspaces/{id}/posts/{post_id}/approval` | write |
| cancel_post | `POST /workspaces/{id}/posts/{post_id}/cancel` | write |
| get_analytics | `GET /workspaces/{id}/analytics` | read |

העמודה האחרונה היא הנחת עבודה סבירה לפי אופי הפעולה. הקובע הוא ההרשאות שהמפתח שלכם קיבל בפועל, וְשַׁגֵּר יחזיר שגיאה ברורה אם חסרה הרשאה.

## שלב 1: מי אני ואיפה אני עובד

```bash
curl -s "$SHAGER/me" -H "Authorization: Bearer $SHAGER_API_KEY"
curl -s "$SHAGER/workspaces" -H "Authorization: Bearer $SHAGER_API_KEY"
```

בְּשַׁגֵּר כל לקוח הוא סביבת עבודה (workspace). אם אין עדיין אף אחת, יוצרים:

```bash
curl -s -X POST "$SHAGER/workspaces" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "רשת מרפאות השן", "timezone": "Asia/Jerusalem"}'
```

אזור הזמן ברירת המחדל הוא `Asia/Jerusalem`, ויש גם שדה `approval_required` שקובע אם פוסטים בסביבה הזו חייבים אישור לקוח לפני תזמון. לסוכנים ברירת המחדל שלו היא false.

## שלב 2: אילו חשבונות מחוברים

```bash
curl -s "$SHAGER/workspaces/$WS/channels" -H "Authorization: Bearer $SHAGER_API_KEY"
curl -s "$SHAGER/workspaces/$WS/groups"   -H "Authorization: Bearer $SHAGER_API_KEY"
```

אם הרשימה ריקה, יוצרים קישור חיבור עם `POST /workspaces/{id}/connect-links` ושולחים אותו לבעל החשבונות. הלקוח מחבר את הפייסבוק, האינסטגרם או היוטיוב שלו דרך הקישור, בלי חשבון בְּשַׁגֵּר ובלי למסור סיסמה. קבוצות חשבונות שימושיות כשיש עשרות עמודים: במקום לרשום מזהים אחד אחד, שולחים `group_ids` וכל החשבונות הפעילים בקבוצה נכנסים לפוסט.

## שלב 3: העלאת מדיה

שַׁגֵּר מושך את הקובץ מכתובת URL. עבור סרטון קצר כדאי לשלוח גם מידות ואורך:

```bash
curl -s -X POST "$SHAGER/workspaces/$WS/media" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/autumn-30s.mp4",
    "file_name": "autumn-30s.mp4",
    "width": 1080,
    "height": 1920,
    "duration_ms": 30000
  }'
```

השדות `width`, `height` וגם `duration_ms` הם מה שמאפשר לְשַׁגֵּר לבדוק מראש אם הסרטון מתאים לפורמט Reel, Short או Story, ולא לגלות את זה רק כשהרשת דוחה אותו. המזהה של המדיה חוזר בתוך `data`, ואותו מעבירים בשדה `media_ids`.

## שלב 4: יצירת פוסט

זו הקריאה שבה רוב הערך נמצא:

```bash
curl -s -X POST "$SHAGER/workspaces/$WS/posts" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "מבצע סתיו, שבוע 1",
    "campaign": "autumn-2026",
    "group_ids": ["GROUP_NORTH"],
    "media_ids": ["MEDIA_ID"],
    "format": "REEL",
    "caption": "בדיקה שנתית לכל המשפחה, עכשיו עם תור תוך שבוע.",
    "per_channel": [
      {"channel_id": "CH_HAIFA",  "caption": "חיפה, התורים לסתיו נפתחו."},
      {"channel_id": "CH_AFULA",  "caption": "בעפולה? יש תורים כבר לשבוע הבא."}
    ],
    "cta_url": "https://example.com/autumn",
    "first_comment": "לקביעת תור בסניף הקרוב:",
    "stagger_seconds": [45, 120]
  }'
```

כמה דברים שקורים כאן מאחורי הקלעים. `cta_url` מקבל לכל חשבון קישור מקוצר ותגיות UTM משלו, כש `utm_content` מזהה את החשבון, והשדה `campaign` הופך לפרמטר `utm_campaign`. `first_comment` עולה כתגובה ראשונה מיד אחרי הפרסום, וזה המקום הטבעי לקישור לליד. `per_channel` מחליף את הכיתוב רק בחשבונות שציינתם, והשאר מקבלים את `caption` הכללי. והשדה `stagger_seconds` קובע את טווח ההשהיה האקראית בין חשבונות של אותה רשת, עם ברירת מחדל של 30 עד 90 שניות. פוסט בלי `schedule_at` נשמר כטיוטה.

ליוטיוב יש שני שדות נוספים: `youtube_title` וגם `youtube_privacy` עם הערכים public, unlisted או private.

## שלב 5: אישור, תזמון ומעקב

אם הלקוח צריך לאשר, שולחים בקשת אישור עם שם הסוקר. הלקוח מאשר דרך קישור, בלי להתחבר:

```bash
curl -s -X POST "$SHAGER/workspaces/$WS/posts/$POST_ID/approval" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewer_name": "מיכל", "reviewer_email": "michal@example.com", "send_email": true}'
```

תזמון דורש זמן בפורמט ISO 8601 עם offset:

```bash
curl -s -X POST "$SHAGER/workspaces/$WS/posts/$POST_ID/schedule" \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule_at": "2026-09-20T09:00:00+03:00"}'
```

אפשר גם לשלוח `schedule_at` כבר בקריאה `create_post` ולחסוך קריאה. לבדיקת מצב משתמשים בפעולה `get_post`, או בפעולה `list_posts` עם `status`, למשל `SCHEDULED`, `PUBLISHED`, `PARTIALLY_PUBLISHED` או `FAILED`. ואחרי כמה ימים:

```bash
curl -s "$SHAGER/workspaces/$WS/analytics?from=2026-09-20T00:00:00%2B03:00" \
  -H "Authorization: Bearer $SHAGER_API_KEY"
```

התשובה כוללת לחיצות לפי חשבון ולפי פוסט בטווח התאריכים. בלי `from`, ברירת המחדל היא 30 הימים האחרונים.

## שגיאות ומגבלת קצב

כל שגיאה חוזרת עם `code` וגם `message` קריאים. שווה לטפל בשלושה מקרים במפורש: 401 על מפתח לא תקין או מבוטל, `sandbox_unclaimed` כשמנסים פעולה חסומה לפני שאדם אישר את סביבת sandbox, וקוד `rejected` כְּשֶׁשַּׁגֵּר בודק את הפוסט מול הכללים של הרשת ומוצא משהו שהיא הייתה דוחה. ההודעה אומרת מה בדיוק לא עבר.

המגבלה היא 120 בקשות בדקה לכל מפתח. בפועל קשה להגיע אליה אם עובדים נכון, כי פוסט אחד עם `group_ids` מכסה עשרות חשבונות בקריאה אחת. מי שמגיע אליה בדרך כלל עושה polling על `get_post` לכל פוסט בנפרד, ועדיף להחליף את זה בפעולה `list_posts`.

## חמישה הרגלים שהופכים סקריפט לאינטגרציה

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

1. **שמרו כל מזהה שחוזר.** מזהה סביבת העבודה, המדיה והפוסט צריכים להישמר אצלכם, בטבלה או בקובץ, יחד עם המקור שממנו נוצרו. כך אפשר לחזור לפוסט, לבדוק את המצב שלו ולבטל אותו בלי לחפש.
2. **אל תיצרו פוסט פעמיים.** אם הסקריפט נופל באמצע וחוזר לרוץ, הוא עלול ליצור את אותה טיוטה שוב. בדקו קודם עם `list_posts` אם כבר קיים פוסט עם אותו `label`.
3. **המתינו כשמגיעים למגבלה.** על שגיאת קצב, חכו ונסו שוב עם השהיה הולכת וגדלה, במקום להפציץ את השרת.
4. **אל תדפיסו את המפתח.** לא בלוג, לא בהודעת שגיאה ולא בצילום מסך. אם הוא דלף, מבטלים אותו במסך הסוכנים ויוצרים חדש.
5. **התחילו בטיוטות.** מפתח בלי `publish` בשבועות הראשונים נותן לכם לראות מה הקוד מייצר לפני שזה עולה לעמודים אמיתיים.

## מה הלאה

אם אתם בונים סוכן ולא סקריפט, אותן פעולות זמינות כשרת MCP בכתובת `https://app.shager.ai/api/mcp`, והחיבור לרוב הכלים לוקח דקות. המדריך [לחיבור שַׁגֵּר אל Claude Code](/blog/connect-shager-to-claude-code) הוא נקודת התחלה טובה, ו[עמוד הסוכנים](/agents) מרכז את כל דרכי החיבור. ואם אתם מתכננים זרימה מלאה מבריף ועד דוח, [המדריך לצינור תוכן של סוכן מקצה לקצה](/blog/agent-content-pipeline-end-to-end) מחבר את כל השלבים.

## שאלות נפוצות

### יש SDK רשמי לְשַׁגֵּר?

אין כרגע SDK או CLI רשמי, CLI של שַׁגֵּר נמצא בפיתוח. מכיוון שיש מפרט OpenAPI 3.1 מלא, אפשר לייצר לקוח בכל שפה עם מחולל קוד סטנדרטי, או פשוט לעבוד עם HTTP ישירות כמו בדוגמאות.

### מה ההבדל בין שליחת schedule_at בקריאה create_post לבין schedule_post?

התוצאה זהה. שליחה בקריאה `create_post` חוסכת קריאה כשהכול מוכן מראש. `schedule_post` מתאים כשיוצרים טיוטה, שולחים לאישור, ומתזמנים רק אחרי שהלקוח אישר.

### איך מבטלים פוסט שכבר תוזמן?

שולחים `POST` לנתיב `/workspaces/{id}/posts/{post_id}/cancel`. אחרי הביטול הסטטוס של הפוסט יהיה `CANCELED`, ואפשר לראות את זה בפעולה `get_post`.

---
Source: https://shager.ai/blog/shager-rest-api-quickstart