REST · OpenAPI 3.1 · MCP

NAGISOT API. למפתחים.

חברו את NAGISOT לכל פלטפורמת צד-שלישי: הפעלת סריקות אתר בענן ומעקב אחריהן, בדיקת דף בודד, קונפיגורציית הווידג'ט ומסמכים משפטיים. REST עם OpenAPI 3.1, ושרת MCP.

llms.txt llms-full.txt @nagisot/mcp

התחלה מהירה

שורת script אחת שמתקינה את הווידג'ט באתר (פאנל נגישות, שכבת תיקון בכל דף, ותיקונים שמורים מהסריקות):

<!-- נדבק לכל אתר. רק החליפו YOUR_SITE_ID. -->
<script src="https://widget.nagis.doogree.co.il/loader.js"
        data-site="YOUR_SITE_ID"
        defer></script>

אימות (API Keys)

צרו מפתח בלוח הניהול. שלוש שיטות להעביר אותו, נבדקות בסדר הזה:

# 1) Bearer token (מומלץ)
Authorization: Bearer pk_live_ABC123...

# 2) Header ייעודי
X-API-Key: pk_live_ABC123...

# 3) Query parameter (כשה-CORS חוסם headers)
?api_key=pk_live_ABC123...

סוגי מפתחות

  • pk_live_* — production, נספר במכסה החודשית של המסלול
  • pk_test_* — sandbox, לא מחויב לעולם, מחזיר נתוני דמה ב-AI endpoints

Scopes

  • widget:read / widget:write — קונפיגורציית הווידג'ט
  • scan:read — הפעלת סריקות אתר ובדיקות דף (/v1/sites/:siteId/scans, /v1/audit)
  • ai:use — endpoints מבוססי AI
  • docs:read / docs:write — מסמכים משפטיים (הצהרת נגישות, פרטיות, תנאים…)
  • * — הכל (מפתח admin)

מפתח חדש מקבל כברירת מחדל: widget:read, widget:write, scan:read, ai:use, docs:read, docs:write.

מסלולים ומגבלות

טוען מ-/v1/tiers…

קודי שגיאה

400 invalid_request          // body פגום או חסר שדה חובה
401 unauthorized | invalid_key  // אין token או שלא מתקבל
402 quota_exceeded            // מכסה חודשית — כולל upgrade_url
403 origin_not_allowed        // Origin לא ברשימה
403 insufficient_scope        // scope חסר — כולל missing[]
403 feature_not_available     // צריך tier גבוה יותר — כולל required_tier
404 not_found
409 scan_running              // כבר רצה סריקה לאתר — כולל scanId ו-poll
429 rate_limited             // כולל retry_after_seconds
503 db_unavailable            // Cloudflare D1 לא זמין רגעית

כל תשובת שגיאה היא JSON תקני:

{
  "error": "quota_exceeded",
  "resource": "ai_calls",
  "used": 100, "limit": 100,
  "upgrade_url": "https://nagis.doogree.co.il/pricing"
}

סריקות

כל אתר רשום נסרק אוטומטית פעם בשבוע בענן — Cloudflare Browser Run, דפדפן Chromium אמיתי, כך שגם אתרים שנבנים ב-JavaScript נבדקים. דרך ה-API אפשר להפעיל סריקה מתי שרוצים ולעקוב אחריה. התוצאות נכנסות לאותם ליקויים ותיקונים של האתר, בדיוק כמו סריקה מהדשבורד, ומשם לווידג'ט.

POST /v1/sites/:siteId/scans כל המסלולים

הפעלת סריקת אתר מלאה. Scope: scan:read. ‏siteId הוא המזהה הציבורי של האתר או ה-UUID הפנימי.

המערכת מגלה את תבניות הדפים של האתר (sitemap + קישורים מדף הבית) — עד 15 תבניות, ועד 50 במסלולים Pro ומעלה — ומכניסה כל דף לתור הסריקה. רמת היעד היא זו שהוגדרה לאתר (ברירת מחדל AA). אין צורך ב-body.

curl -X POST https://api.nagis.doogree.co.il/v1/sites/SITE_ID/scans \
  -H "Authorization: Bearer pk_live_..."

# 202 Accepted
{
  "scanId": "…",
  "pagesQueued": 12,
  "status": "running",
  "poll": "/v1/sites/SITE_ID/scans/SCAN_ID"
}

# 409 — כבר רצה סריקה לאתר הזה
{ "error": "scan_running", "scanId": "…", "poll": "/v1/sites/SITE_ID/scans/SCAN_ID" }
GET /v1/sites/:siteId/scans/:scanId כל המסלולים

התקדמות וסיכום של סריקה. מפתח של בעל האתר. ‏status: running ← completed או failed. זמנים בשניות Unix.

{
  "scanId": "…",
  "status": "running",          // running | completed | failed
  "trigger": "manual",
  "targetLevel": "AA",
  "pagesPlanned": 12,
  "pagesScanned": 7,
  "issuesFound": 41,
  "fixesCreated": 18,
  "startedAt": 1761400000,
  "finishedAt": null,
  "error": null                 // למשל "2 page(s) failed"
}
POST /v1/audit כל המסלולים

בדיקת דף בודד, לכל כתובת. Scope: scan:read. הבדיקה רצה במנוע הדפדפן בענן (Cloudflare Browser Run), עם צי המכשירים כגיבוי, ומחזירה דוח. היא לא יוצרת תיקונים לאתר — לשם כך משתמשים בסריקת אתר.

Body: url (כתובת http/https מלאה, חובה), level (‏A / AA / AAA, ברירת מחדל AAA). תשאול: GET /v1/audit/:jobId.

curl -X POST https://api.nagis.doogree.co.il/v1/audit \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.co.il/product/1","level":"AA"}'

# 202 Accepted
{ "jobId": "job_…", "status": "queued", "poll": "/v1/audit/job_…" }

# GET /v1/audit/job_…
{
  "jobId": "job_…", "url": "https://example.co.il/product/1", "level": "AA",
  "status": "done",             // queued | claimed | done | failed
  "queuePosition": 0,
  "error": null,
  "report": { … },
  "createdAt": 1761400000, "finishedAt": 1761400042
}

Endpoints

טוען מ-/v1/openapi.json…

MCP Server

הטמיעו את NAGISOT ב-Claude Code, Cursor או Zed עם MCP. ה-AI עצמו ינהל את הקונפיגורציה ויפעיל סריקות:

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "nagisot": {
      "command": "npx",
      "args": ["-y", "@nagisot/mcp"],
      "env": { "NAGISOT_API_KEY": "pk_live_..." }
    }
  }
}

סריקות מתוך ה-AI

  • nagisot_scan — עם site_id: סריקת אתר מלאה (‏POST /v1/sites/:siteId/scans) — גילוי תבניות דפים וסריקה בדפדפן אמיתי, והתוצאות הופכות לליקויים ולתיקונים. עם url בלבד: בדיקת דף בודד (‏POST /v1/audit).
  • nagisot_scan_status — ‏site_id + scan_id: התקדמות וסיכום של סריקת אתר (דפים מתוכננים/נסרקו, ליקויים, תיקונים, סטטוס).

כל ה-Tools

nagisot_whoami, nagisot_tiers, nagisot_get_widget_config, nagisot_set_widget_config, nagisot_get_site_state, nagisot_set_site_state, nagisot_get_consent, nagisot_set_consent, nagisot_usage, nagisot_scan, nagisot_scan_status, nagisot_list_doc_types, nagisot_list_docs, nagisot_get_doc, nagisot_create_doc, nagisot_edit_doc.

SDKs

  • JavaScript / TypeScript — @nagisot/sdk (בקרוב)
  • Python — nagisot ב-PyPI (בקרוב)
  • REST — זמין עכשיו, ראו את ה-OpenAPI Spec

Webhooks (בקרוב — Pro+)

קבלו התראות אירועים: scan.completed, fix.needs_approval, quota.warning, quota.exceeded.