WebApp API Reference

Endpoints

Endpoints
Endpoint	Method	תיאור	דורש אימות	Request Body	Response
`/`	GET	דף הבית	❌		HTML
`/login`	GET	דף התחברות (Telegram Widget)	❌		HTML
`/auth/telegram`	POST	אימות Telegram (hash verify)	❌	`{id, first_name, ...}`	`{"success": true}`
`/logout`	GET	התנתקות	✅		Redirect
`/dashboard`	GET	דשבורד	✅		HTML
`/tools/code`	GET	Code Tools (Playground: עיצוב/בדיקות/הרצת קוד)	✅		HTML
`/files`	GET	רשימת קבצים (סינון, חיפוש ודפדוף)	✅	Query: `?q=...&lang=...&category=...&sort=created_at_desc&cursor=...&repo=...`	HTML
`/file/<id>`	GET	צפייה בקובץ	✅		HTML
`/download/<id>`	GET	הורדת קובץ	✅		File Download
`/html/<id>`	GET	תצוגת HTML בטוחה	✅		HTML (iframe)
`/md/<id>`	GET	תצוגת Markdown	✅		HTML (rendered)
`/api/sticky-notes/reminders/summary`	GET	סיכום מינימלי לבועה הקבועה (האם יש פתקים ממתינים + מונה)	✅		`{"ok": true, "has_due": true, "count_due": 3, "next": {"note_id": "...", "file_id": "...", "remind_at": "..."}}`
`/api/sticky-notes/reminders/list`	GET	רשימת פתקים ממתינים עם תצוגה מקדימה (6 מילים) וקישור לעוגן	✅	Query: `?limit=20`	`{"ok": true, "count": 3, "items": [{"note_id": "...", "file_id": "...", "preview": "...", "anchor_id": "h2-intro"}]}`
`/api/v1/announcements/active`	GET	ההכרזה הפעילה היחידה להצגה בבאנר (או `null` אם אין)	✅		`{"id": "...", "text": "...", "link": "/path"}` או `null`
`/api/sticky-notes/reminders/ack`	POST	סימון תזכורת כ־acknowledged (המשתמש פתח)	✅	`{"note_id": "..."}`	`{"ok": true}`
`/api/sticky-notes/note/<note_id>/reminder`	POST	קביעת תזכורת לפתק (קיצורי זמן/תאריך שעה)	✅	`{"preset": "1h"\|"3h"\|"24h"\|"1w"\|"today-21"\|"tomorrow-09", "tz": "Asia/Jerusalem"}` או `{"at": "2025-11-15T09:00", "tz": "Asia/Jerusalem"}`	`{"ok": true, "remind_at": "2025-11-15T07:00:00+00:00"}`
`/api/sticky-notes/note/<note_id>/snooze`	POST	דחיית תזכורת ב‑X דקות	✅	`{"minutes": 60}`	`{"ok": true, "remind_at": "..."}`
`/api/welcome/ack`	POST	סימון הדגל `has_seen_welcome_modal` והסתרת מודאל ה־Welcome לצמיתות	✅		`{"ok": true}`
`/api/shared/save`	POST	שמירת שיתוף פנימי כקובץ Markdown תחת חשבון המשתמש	✅	`{"share_id": "string", "file_name": "optional override"}`	`{"ok": true, "file_id": "...", "file_name": "...", "version": 1}`
`/api/code/run/limits`	GET	מגבלות וזמינות להרצת קוד (Premium/Admin בלבד)	✅		`{"enabled": true\|false, "limits": {...}, "allowed_imports": [...]}`
`/api/code/run`	POST	הרצת קוד Python (Premium/Admin בלבד)	✅	`{"code": "...", "timeout": 5, "memory_limit_mb": 128}`	`{"success": true\|false, "stdout": "...", "stderr": "...", "exit_code": 0, "execution_time_ms": 12, "truncated": false, "error": null}`
`/api/stats`	GET	סטטיסטיקות	✅		JSON

Authentication Flow

        sequenceDiagram
    participant U as User
    participant W as WebApp
    participant T as Telegram
    U->>W: GET /login
    W-->>U: Login page with Telegram Widget
    U->>T: Click "Login"
    T->>W: POST /auth/telegram (user data + hash)
    W->>W: Verify hash with BOT_TOKEN
    W-->>U: Set session cookie
    U->>W: GET /dashboard
    W-->>U: Dashboard (authenticated)

Response Schema Example

{
  "total_files": 156,
  "languages": {
    "python": 45,
    "javascript": 32,
    "java": 20
  },
  "recent_files": [
    {
      "id": "507f1f77bcf86cd799439011",
      "file_name": "example.py",
      "language": "python",
      "created_at": "2025-10-10T10:30:00Z"
    }
  ]
}

Errors

{"error": "Authentication required", "redirect": "/login"}

{"error": "File not found", "file_id": "507f1f77bcf86cd799439011"}

שגיאות נפוצות – `POST /api/shared/save`

{"error": "Missing share_id"}

{"error": "Share not found", "share_id": "abcd1234"}

{"error": "Invalid file name"}

קישורים

מסנן ושדות קלט ל-`/files`

טבלת פרמטרים

`/files` parameters
פרמטר	סוג	ברירת מחדל	תיאור
`q`	string		מחרוזת חיפוש (טקסט חופשי)
`lang`	string		סינון לפי שפת תכנות (`python`, `js` וכו«)
`category`	string		קטגוריית קובץ/תיוג לוגי
`sort`	string	`created_at_desc`	סדר מיון (`created_at_desc`/`created_at_asc`)
`cursor`	string		קורסור לדפדוף מבוסס זמן+``_id`` (ראו Cursor-based Pagination (created_at / _id))
`repo`	string		סינון לפי ריפו/מקור אם רלוונטי

דוגמאות בקשה

# חיפוש בסיסי
curl -isS "https://<host>/files?q=pagination&lang=python"

# דף שני עם קורסור
curl -isS "https://<host>/files?cursor=<TOKEN>"

דוגמאות תגובה

<!-- HTML מקוצר לצורך דוגמה -->
<div class="files-list">
  <div class="file">
    <a href="/file/507f1f77bcf86cd799439011">example.py</a>
    <span class="lang">python</span>
    <time datetime="2025-10-10T10:30:00Z">2025-10-10</time>
  </div>
</div>