עבור לתוכן
cutty.dev
למפתחים

API ושרת MCP

צרו ונהלו קישורים קצרים מתוך הקוד שלכם — דרך ה-REST API או דרך שרת MCP בעוזר ה-AI שלכם.

ל-cutty יש API ציבורי ושרת MCP. הראשון מאפשר ליצור ולשנות קישורים מתוך הקוד; השני עובד ישירות מתוך עוזר AI שמדבר בפרוטוקול MCP. שניהם משתמשים באותו מפתח API.

מפתח API

אמתו כל קריאה בעזרת כותרת:

Authorization: Bearer ck_your_key

איפה משיגים מפתח: התחברו, פתחו את לוח הבקרה → API keys → Create key. המפתח המלא (הוא מתחיל ב-ck_) מוצג רק פעם אחת, ברגע היצירה — שמרו אותו במקום בטוח מיד. המגבלה היא 120 בקשות לדקה לכל מפתח.

כתובת בסיס

כל נקודות הקצה של REST נמצאות תחת https://cutty.dev/api/v1. הבקשות והתשובות הן בפורמט JSON.

יצירת קישור

POST /api/v1/links — גוף ה-JSON צריך לכל הפחות url. כל השאר אופציונלי:

  • url — כתובת היעד (חובה)
  • slug — סיומת מותאמת אישית, 3–40 תווים; השמיטו כדי לקבל סיומת אקראית
  • expiresAt — תאריך תפוגה בפורמט ISO 8601
  • maxHits — מגבלת קליקים (1–1,000,000)
  • password — סיסמה שמגינה על הקישור
  • tags — תוויות מופרדות בפסיקים לארגון בלוח הבקרה
  • folder — שם התיקייה שאליה נכנס הקישור
  • utmSource, utmMedium, utmCampaign — פרמטרי UTM שמתווספים בעת ההפניה

התשובה מחזירה slug, shortUrl ו-target.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

רשימה וקישור בודד

GET /api/v1/links מחזיר את כל הקישורים שלכם. GET /api/v1/links/{slug} — פרטים של קישור אחד.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

עדכון ומחיקה

PATCH /api/v1/links/{slug} מעדכן את השדות שאתם מעבירים, DELETE /api/v1/links/{slug} מוחק את הקישור.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

דרך PATCH אפשר להגדיר, בין היתר: targetUrl, expiresAt, maxHits, status, password, tags, folder, ובנוסף את השדות המתקדמים שלמטה. שדה שמוגדר ל-null (או למחרוזת ריקה) מאפס את המאפיין הזה.

טירגוט, A/B ושדות מתקדמים

אותם הדברים שתמצאו בעורך הקישורים זמינים גם דרך ה-API:

  • rules — מערך של כללי הפניה לפי מדינה או מכשיר, למשל [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — רוטציית A/B: מערך [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}]; בשימוש כשאף כלל לא מתאים
  • startsAt — התאריך (ISO 8601) שבו הקישור עולה לאוויר; לפניו הקישור מחזיר 425
  • webhookUrl — כתובת שמקבלת התראת POST בכל קליק (fire-and-forget)
  • serveOg יחד עם ogTitle, ogDescription, ogImageUrl — כרטיס תצוגה מקדימה מותאם לסורקי הרשתות החברתיות (בני אדם עדיין מופנים ליעד)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

פעולות בכמות

POST /api/v1/bulk יוצר קישורים רבים בבקשה אחת. העבירו מערך links (כל פריט כמו יצירה רגילה), עד 500 בכל פעם. התשובה מחזירה תוצאה לכל שורה.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

סטטיסטיקות קישור

GET /api/v1/links/{slug}/stats מחזיר סיכום קליקים: הסך הכול, פירוט לפי מכשיר ודפדפן, וההתפלגות לאורך 24 השעות האחרונות.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

שרת MCP

אם אתם עובדים עם עוזר AI, אפשר לחבר את cutty דרך MCP (Model Context Protocol) ולבקש ממנו לקצר ולארגן קישורים ישירות בשיחה. השרת רץ בכתובת https://mcp.cutty.dev/mcp מעל Streamable HTTP, ואתם מאמתים עם אותו מפתח API — הכותרת Authorization: Bearer ck_....

רשימת הכלים המלאה, קטעי חיבור מוכנים ודוגמאות נמצאים בעמוד ייעודי: שרת ה-MCP של cutty.

משהו לא עובד?

כתבו ל-[email protected] — אני עונה באותו יום.