תיעוד API

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

כתובת בסיס ומעטפת תשובות

כל הקריאות נשלחות אל:

https://ktzr.io/api

תשובה מוצלחת עטופה תמיד ב-‏data‏; שגיאה מוחזרת כ-‏error‏ עם הודעה קריאה:

{ "data": { ... } }        // 2xx
{ "error": "readable message" }  // 4xx / 5xx

אימות

שתי דרכים להזדהות:

אסימון זיהוי של Firebase (משתמשים מחוברים באפליקציה):

Authorization: Bearer <Firebase ID token>

מפתח API (לשרתים ולסקריפטים). מפתחות נוצרים באפליקציה או דרך ה-API, מתחילים תמיד ב-‏rsvp_live_sk_‏, ומוצגים פעם אחת בלבד בעת היצירה:

X-API-Key: rsvp_live_sk_...

זיהוי סביבת העבודה

כל משאב ב-‏/api/v1‏ שייך לסביבת עבודה (workspace). הזיהוי נקבע כך:

• קריאה עם מפתח API פועלת תמיד על סביבת העבודה שהמפתח שייך לה - הפרמטר workspace מתעלם ממנו.
• קריאה עם אסימון זיהוי יכולה לציין ?workspace={slug}; בלעדיו נבחרת סביבת ברירת המחדל של החשבון.
• סביבה שאינה קיימת או שאינכם חברים בה עונה 404 - קיומה לעולם אינו נחשף.

מגבלות קצב ומכסות

• יצירה, עריכה ומחיקה של קישורים חולקות תקציב אחד: 20 פעולות בשעה לכל סביבת עבודה (ברירת מחדל). מעבר לתקציב עונה 429 עם כותרת Retry-After בשניות.
• מכסת קישורים כוללת: 50 קישורים לחשבון (ברירת מחדל). חריגה עונה 403.
• חשבון חדש: עד 5 קישורים ב-24 השעות הראשונות.
• יצירת קישור מחזירה גם כותרת X-RateLimit-Remaining עם יתרת התקציב השעתי.
• דיווחי שימוש לרעה (ללא הזדהות): עד 5 בשעה לכל כתובת IP.

כל הנתיבים

יצירת קישור

שולחים כתובת, מקבלים קישור קצר. domain אופציונלי (ברירת מחדל ktzr.io, לפי הרשאות החשבון); code - כתובת בהתאמה אישית של 3–50 תווים מתוך ‏[a-zA-Z0-9_-]‏ - זמין כיום לחשבונות מנהל בלבד (מתוכנן ל-Pro); tagIds - עד 10 מזהי תגיות קיימות.

כל יעד נבדק מול Google Web Risk: יעד מסוכן נדחה עם 422.

curl -X POST https://ktzr.io/api/v1/links \
  -H "X-API-Key: rsvp_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very/long/path?with=parameters"}'

HTTP/2 201
X-RateLimit-Remaining: 19

{
  "data": {
    "shortCode": "aB3xK9qZ",
    "shortUrl": "https://ktzr.io/aB3xK9qZ",
    "domain": "ktzr.io",
    "tagIds": []
  }
}

HTTP/2 422

{ "error": "This destination is flagged as unsafe (SOCIAL_ENGINEERING) and cannot be shortened." }

רשימת קישורים

עימוד מבוסס-סמן: limit בין 1 ל-100 (ברירת מחדל 25), cursor מהתשובה הקודמת (אטום - לא לפרסר), status אחד מ-active / disabled / deleted (בלי סינון, קישורים שנמחקו אינם מוצגים), tag מזהה תגית, search קידומת של הקוד הקצר. nextCursor הוא null בעמוד האחרון; עמוד יכול להחזיר פחות מ-limit גם כשיש עוד תוצאות - ממשיכים לפי הסמן.

curl "https://ktzr.io/api/v1/links?limit=25&status=active&search=aB" \
  -H "Authorization: Bearer <ID token>"

{
  "data": {
    "links": [
      {
        "shortCode": "aB3xK9qZ",
        "shortUrl": "https://ktzr.io/aB3xK9qZ",
        "originalUrl": "https://example.com/very/long/path?with=parameters",
        "domain": "ktzr.io",
        "status": "active",
        "tagIds": ["fJ29xPqLmA31Bc7Yd0Ek"],
        "visits": 42,
        "botVisits": 7,
        "createdAt": "2026-08-30T10:15:00.000Z"
      }
    ],
    "nextCursor": null
  }
}

סטטיסטיקות

סך הקליקים ופילוח יומי (UTC) של הימים האחרונים: days בין 1 ל-90, ברירת מחדל 30. ימים בלי קליקים חוזרים כאפסים. בוטים (תצוגות מקדימות, סורקים, סקריפטים) נספרים בנפרד ב-botVisits.

curl "https://ktzr.io/api/v1/stats/aB3xK9qZ?days=7" \
  -H "X-API-Key: rsvp_live_sk_..."

{
  "data": {
    "shortCode": "aB3xK9qZ",
    "total": 42,
    "botTotal": 7,
    "daily": [
      { "date": "2026-08-24", "visits": 5, "botVisits": 1 },
      { "date": "2026-08-25", "visits": 9, "botVisits": 2 }
    ]
  }
}

עריכה, מחיקה והיסטוריה

• PATCH מקבל url חדש (נבדק שוב מול Web Risk) או tagIds חדשים. עריכת יעד נרשמת בהיסטוריה.
• DELETE היא מחיקה רכה: הקישור עונה 410 לכל דורש, והקוד לעולם לא ימוחזר. פעולה על קישור שכבר נמחק עונה 410.
• GET ‏/api/v1/links/{code}/history‏ מחזיר עד 50 עריכות יעד, מהחדשה לישנה.

תגיות

שם עד 32 תווים, צבע אחד מתוך: red, orange, yellow, green, teal, blue, purple, pink. שם כפול באותה סביבה עונה 409. מחיקת תגית אינה משנה קישורים - המזהה פשוט מסונן מהם בקריאה.

מפתחות API

ניהול מפתחות דורש אסימון זיהוי (מפתח אינו יכול לנהל מפתחות). עד 10 מפתחות פעילים; expiresIn בימים (1–365, אופציונלי); permissions הן canCreate / canRead / canUpdate / canDelete וברירת המחדל של כולן true. DELETE משבית את המפתח (ביטול הרשאה).

דיווח ציבורי על שימוש לרעה

נתיב פתוח ללא הזדהות. reason בין 10 ל-1000 תווים; reporterEmail אופציונלי. התשובה היא תמיד 202 - קיומו של קוד לעולם אינו נחשף. שימו לב: תשובת נתיב זה אינה במעטפת data.

curl -X POST https://ktzr.io/api/abuse \
  -H "Content-Type: application/json" \
  -d '{"code": "aB3xK9qZ", "reason": "This link leads to a phishing page impersonating a bank"}'

HTTP/2 202

{ "message": "Report received" }

קודי שגיאה

דוגמה לשגיאת 403 (מכסה):

HTTP/2 403

{ "error": "You have reached your maximum limit of 50 URLs. Please delete some existing URLs to create new ones." }