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)

/svg/<id>

GET

תצוגת SVG מרונדרת, עם החלפת רקע

✅

HTML

/raw_svg/<id>

GET

ה-SVG הגולמי עבור ה-<img> שבעמוד התצוגה

✅

image/svg+xml

/api/sticky-notes/reminders/summary

GET

סיכום מינימלי לבועה הקבועה (האם יש פתקים ממתינים, מונה, ובעוד כמה שניות לשאול שוב)

✅

{"ok": true, "has_due": true, "count_due": 3, "next_in_seconds": 300}

/api/sticky-notes/reminders/list

GET

רשימת פתקים ממתינים, כל אחד בשם שלו (preview: שם הפתק, ובלעדיו השורה הראשונה שלו — sticky_notes_target.note_label) וקישור לעוגן

✅

Query: ?limit=20

{"ok": true, "count": 3, "items": [{"note_id": "...", "file_id": "...", "preview": "...", "anchor_id": "h2-intro", "remind_at": "2026-09-20T09:00:00+00:00"}]}

/api/v1/announcements/active

GET

ההכרזה הפעילה היחידה להצגה בבאנר (או null אם אין)

✅

{"id": "...", "text": "...", "link": "/path"} או null

/api/sticky-notes/reminders/ack

POST

סימון תזכורת כ־acknowledged (המשתמש פתח). remind_at הוא המועד שההתראה או החלונית נשאו: איתו האישור סוגר רק את המסמך שעדיין נושא את המועד הזה (תזכורת שנדרכה מחדש או נדחתה מאז עונה 404); בלעדיו — האישור אינו נקשר למועד; מחרוזת שאינה ISO ← 400 invalid_remind_at

✅

{"note_id": "...", "remind_at": "2026-09-20T09:00:00+00:00"}

{"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} — מספר שלם בין 1 ל‑1440, ברירת מחדל 60; טיפוס אחר ← 400 Invalid minutes, גוף שאינו אובייקט ← 400 invalid_payload

{"ok": true, "remind_at": "..."}

/api/sticky-notes/note/<note_id>/archive

POST

העברת פתק לארכיון, מכל יעד (ארכיון: היעד הרביעי). פתק בלי שם דורש title (בלעדיו ← 400 title_required); שם ארוך מהתקרה נדחה ולא נחתך (400 title_too_long עם max). ארכיון מלא ← 409 archive_quota_exceeded עם max, וספירה שנכשלה ← 409 note_quota_unknown. פתק שאינו של המשתמש ← 404 note_not_found; פתק שכבר בארכיון ← 200 עם already_archived: true, בלי כתיבה. השרשורים הפתוחים של הפתק נסגרים; threads_resolved: null אומר שהסגירה נכשלה, וההעברה עצמה נשארת

✅

{"title": "..."} — אופציונלי; גוף שאינו אובייקט ← 400 invalid_payload

{"ok": true, "already_archived": false, "note": {...}, "threads_resolved": 1}

/api/sticky-notes/archive

GET

כרטיסי עמוד הארכיון — מהחדש לישן לפי זמן ההעברה, בלי גוף הפתקים. max היא התקרה שחלה על המשתמש, או null לאדמין. שאילתה שנכשלה ← 500, ולא רשימה ריקה

✅

{"ok": true, "notes": [{"id": "...", "title": "...", "color": "#...", "color_id": "...", "archived_at": "..."}], "count": 1, "max": ...}

/api/sticky-notes/archive/<note_id>

GET

פתק אחד מהארכיון, מלא, עם תקצירי השרשורים שלו — כשפותחים כרטיס. פתק שאינו בארכיון או אינו של המשתמש ← 404 note_not_found; מזהה פגום ← 400 invalid_note_id. כשל בקריאת השרשורים אינו מפיל את התשובה: threads_unavailable: true

✅

{"ok": true, "note": {...}}

/api/sticky-notes/note/<note_id>/files-page-pin

POST

נעיצת פתק לוח לראש עמוד הקבצים (נעיצה לעמוד הקבצים: שדה לצד היעד, ולא יעד). הפתק נשאר בלוח, ו-updated_at אינו משתנה. פתק שאינו של המשתמש ← 404 note_not_found; פתק בארכיון ← 409 note_archived; פתק שאינו פתק לוח ← 400 not_a_board_note; כבר נעוץ ← 200 עם already_pinned: true, בלי כתיבה. תקרה מלאה ← 409 files_page_pins_full עם max (התקרה שחלה), pinned ו-device_limited (המכשיר הוריד את התקרה), וספירה שנכשלה ← 409 note_quota_unknown. אין הסרה אוטומטית של פתק ישן

✅

{"device_limit": 2} — אופציונלי: כמה כרטיסים נכנסים בשורה בעמוד הקבצים במסך שממנו נועצים. רק מוריד את התקרה. שדה שלא נשלח, null, או גוף ריק ← התקרה הכללית; ערך שנשלח חייב להיות int שאינו bool ואינו שלילי, ואחרת 400 invalid_device_limit. גוף שנשלח ואינו אובייקט — גם JSON פגום או null — ← 400 invalid_payload

{"ok": true, "already_pinned": false, "files_page_pinned_at": "...", "note": {...}}

/api/sticky-notes/note/<note_id>/files-page-pin

DELETE

הסרת הנעיצה מעמוד הקבצים; הפתק נשאר בלוח. פתק שאינו של המשתמש ← 404 note_not_found; פתק שאינו נעוץ ← 200 עם already_unpinned: true

✅

{"ok": true, "already_unpinned": false, "files_page_pinned_at": null}

/api/sticky-notes/files-page

GET

כרטיסי ראש עמוד הקבצים — הפתקים הנעוצים, מהראשון שננעץ לאחרון. label הוא השם, ובלעדיו השורה הראשונה של הפתק (sticky_notes_target.note_label). max היא התקרה הכללית. שאילתה שנכשלה ← 500, ולא רשימה ריקה

✅

{"ok": true, "notes": [{"id": "...", "label": "...", "color": "#...", "color_id": "...", "files_page_pinned_at": "..."}], "count": 1, "max": 4}

/api/sticky-notes/files-page/<note_id>

GET

פתק נעוץ אחד, מלא, עם תקצירי השרשורים שלו — כשפותחים כרטיס בעמוד הקבצים. פתק שאינו נעוץ, בארכיון או אינו של המשתמש ← 404 note_not_found; מזהה פגום ← 400 invalid_note_id. כשל בקריאת השרשורים: threads_unavailable: true

✅

{"ok": true, "note": {...}}

/api/sticky-notes/search

GET

חיפוש בפתקים של המשתמש, בשם ובגוף, בכל היעדים (חיפוש בפתקים: למה רג’קס ולא $text). q חובה: ריק ← 400 empty_query, ארוך מהתקרה ← 400 query_too_long עם max, ותו NUL ← 400 invalid_query. color מסנן לפי צבע (מזהה לא מוכר ← 400 invalid_color עם allowed). פתקי הארכיון מוסתרים, ו-include_archived=1 מוסיף אותם; כל ערך אחר מלבד 0 או כלום ← 400 invalid_include_archived עם allowed. limit לא מספרי או קטן מאחד ← ברירת המחדל, וגדול מהתקרה ← נחתך. כל פגיעה מחזירה תצוגה מקדימה, ולא את גוף הפתק

✅

{"ok": true, "query": "...", "color_id": "", "include_archived": false, "count": 1, "truncated": false, "results": [{"id": "...", "url": "/note/...", "title": "...", "preview": "...", "preview_truncated": false, "color": "#...", "color_id": "...", "updated_at": "...", "target": "board", "board_id": "..."}]}

/api/sticky-notes/note/<note_id>/threads

GET

תקצירי שרשורי התגובות של הפתק, בלי התגובות — לבועות. פתק שאינו של המשתמש ← 404 note_not_found (שרשורי תגובות: השרת)

✅

{"ok": true, "threads": [{"id": "...", "number": 1, "status": "open", "comment_count": 2, "awaits_user": true}]}

/api/sticky-notes/note/<note_id>/threads/<thread_id>

GET

שרשור אחד עם כל התגובות שלו, ותקצירי כל השרשורים של הפתק

✅

{"ok": true, "thread": {..., "resolved_by_label": "", "resolved_at": null, "comments": [{"id", "author_kind", "author_label", "author_initials", "author_tone", "working_on", "body", "created_at"}]}, "threads": [...]}

/api/sticky-notes/note/<note_id>/threads

POST

שרשור חדש עם התגובה הראשונה שלו (201)

✅

{"body": "..."} — עד MAX_COMMENT_CHARS תווים; ריק ← 400 empty_body, ארוך ← 400 body_too_long

{"ok": true, "action": "created", "thread_id": "...", "thread": {...}, "comment": {...}, "threads": [...]} — נקרא מהמסד אחרי הכתיבה. כל אחד משני השדות יכול להיות null לבד, כי הם נקראים בנפרד: thread — כשהקריאה החוזרת של השרשור החדש נכשלה (רק ביצירה; בשאר הכתיבות הוא המסמך שהכתיבה עצמה החזירה), ו-threads — כשקריאת התקצירים נכשלה. null פירושו ”לא ידוע, קראו שוב“, ולא ”ריק“

/api/sticky-notes/note/<note_id>/threads/<thread_id>/comments

POST

תשובה בשרשור. reopen (ברירת מחדל true) פותח שרשור שנפתר באותה כתיבה; false משאיר אותו נפתר

✅

{"body": "...", "reopen": true} — reopen שאינו בוליאני ← 400 invalid_reopen; שרשור מלא ← 409 thread_full / 409 thread_too_long

כמו ביצירה, עם "action": "replied"

/api/sticky-notes/note/<note_id>/threads/<thread_id>/resolve

POST

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

✅

{} או {"body": "..."} — שרשור שכבר נפתר ← 409 already_resolved, ושום דבר לא נכתב

כמו ביצירה, עם "action": "resolved"

/api/sticky-notes/note/<note_id>/threads/<thread_id>/reopen

POST

פתיחה מחדש של שרשור שנפתר, בלי תגובה

✅

אין גוף. שרשור פתוח ← 409 not_resolved

כמו ביצירה, עם "action": "reopened"

/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>