# NAGISOT — Full LLM-Friendly Reference This document is a single-file, copy-pasteable reference for AI agents and LLM-based coding assistants. Everything you need to embed, integrate, or talk about NAGISOT lives here. Updated: 2026-05-30 --- ## What NAGISOT is A universal accessibility platform built on Cloudflare. Three deliverables: 1. **Drop-in widget** (`widget.js`) — a single ` ``` Public site IDs are created in the dashboard at https://nagis.doogree.co.il/sites after signup. --- ## Quickstart for integrators (programmatic) ### 1. Get an API key ```bash # Sign up at https://nagis.doogree.co.il/signup, then: curl -X POST https://api.nagis.doogree.co.il/users/me/api-keys \ -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \ -H "Content-Type: application/json" \ -d '{"name": "My Integration", "mode": "live"}' # Response includes `plaintext` field — SHOWN ONCE. Store it safely. ``` ### 2. Call the API ```bash # Discovery (no auth) curl https://api.nagis.doogree.co.il/v1 curl https://api.nagis.doogree.co.il/v1/tiers curl https://api.nagis.doogree.co.il/v1/openapi.json # Authenticated — inspect your own key curl https://api.nagis.doogree.co.il/v1/me \ -H "Authorization: Bearer pk_live_..." # Get widget config for a site curl https://api.nagis.doogree.co.il/v1/widget-config/SITE_ID \ -H "Authorization: Bearer pk_live_..." # Current month usage curl https://api.nagis.doogree.co.il/v1/usage \ -H "Authorization: Bearer pk_live_..." ``` --- ## Authentication Three ways to pass an API key, checked in this order: 1. `Authorization: Bearer pk_live_<32 chars>` 2. `X-API-Key: pk_live_<32 chars>` 3. `?api_key=pk_live_<32 chars>` — for browser SDKs when CORS blocks custom headers Keys come in two modes: - **`pk_live_*`** — production, counts toward your billing - **`pk_test_*`** — sandbox, never billed (planned: returns mock data on AI endpoints) Each key has: - **Scopes**: `widget:read`, `widget:write`, `scan:read`, `scan:write`, `ai:use`, `*` (all) - **Site restriction**: optional — key only valid for one specific site - **Origin allowlist**: optional — key only valid from specific browser origins (e.g. `example.com`, `*.example.com`) - **Rate-limit override**: optional — lower the per-key per-minute limit below tier default --- ## Tiers and limits All prices pre-VAT (B2B standard in Israel). Signup is free, no credit card required. | Tier | Price | API/mo | AI/mo | Sites | Keys | RPM | WCAG | Panel CTA | Page banner | |---|---|---|---|---|---|---|---|---|---| | Free | ₪0 | 10,000 | 50 | 1 | 2 | 60 | A | ✅ | ✅ | | Starter | ₪30+VAT/mo | 25,000 | 200 | 1 | 3 | 120 | A | ❌ | ❌ | | Pro | ₪99+VAT/mo | 100,000 | 2,000 | 5 | 10 | 300 | A+AA | ❌ | ❌ | | Business | ₪249+VAT/mo | 1,000,000 | 20,000 | 50 | 50 | 1,000 | A+AA+AAA | ❌ | ❌ | | Enterprise | custom | unlimited | unlimited | unlimited | unlimited | 5,000 | All | ❌ | ❌ | ## Free-tier ad model The Free tier carries two distinct ad surfaces, each requiring its own opt-in checkbox at signup (Israeli consumer law: bundled consent is invalid for materially different terms): 1. **Panel CTA** — a small "Want this widget on your site too? Free →" card at the bottom of the accessibility panel, visible only when a visitor opens it. Permanent for Free tier; standard practice for every overlay widget on the market. 2. **Page banner** — a 50px bottom-of-page bar, shown once per visitor session, auto-fades after 12 seconds. Dismissible at any time. Lives in its own Shadow DOM so it can't break or be broken by site CSS. Both removed by upgrading to Starter (₪30+VAT/mo) or higher. We do NOT inject third-party ads. No pop-ups, no interstitials, no cross-site tracking, no visitor fingerprinting. The disclosure appears: (a) on the pricing page, (b) in the signup form as two required checkboxes, (c) as a top-level §3 in the Terms of Service — never buried in fine print. There's a global kill-switch in KV (`feature:page_banner = "0"`) that lets us silently disable the page banner across all Free-tier sites if it turns out to harm adoption. The panel CTA is permanent. Feature flags per tier (see `apps/api/src/lib/tiers.ts`): - `aiFixes` (Pro+) — alt-text generation, simplify language, etc. - `pdfReports` (Pro+) — downloadable compliance reports - `comprehensiveReports` (Business+) — full crawl + screenshots - `captions` (Pro+) — Whisper-generated video/audio captions - `customBranding` (Pro+) — replace "NAGISOT" with your own brand on the panel - `webhooks` (Pro+) — get notified when scans complete or fixes need approval - `multiSite` (Pro+) — more than 1 site per account - `prioritySupport` (Business+) - `whiteLabel` (Enterprise) — full white-label - `sla` (Enterprise) — written uptime/latency SLA --- ## Endpoints (v1) All paths under `https://api.nagis.doogree.co.il/v1/`. ### Discovery (no auth) - `GET /v1` — root, returns metadata about the API - `GET /v1/tiers` — list of tiers and their limits - `GET /v1/openapi.json` — OpenAPI 3.1 spec ### Account - `GET /v1/me` — info about the calling key (id, prefix, scopes, tier, limits, features) - `GET /v1/usage` — current-month usage broken down by day ### Widget - `GET /v1/widget-config/:siteId` — fetch resolved widget config (3-tier inheritance) - `PUT /v1/widget-config/:siteId` — update site widget config (requires `widget:write` scope) ### Scans - `POST /v1/scan` — trigger an accessibility scan of a URL ### AI - `POST /v1/ai/alt-text` — AI-generate alt text for an image (requires Pro+) ### Headers returned - `X-NAGISOT-Tier` — `free`/`pro`/`business`/`enterprise` - `X-RateLimit-Limit` — requests/minute on this tier - `Retry-After` — only on 429 responses ### Error codes - `400 invalid_request` — malformed body or missing required field - `401 unauthorized` / `401 invalid_key` — no token or token doesn't resolve - `402 quota_exceeded` — monthly quota hit; includes `upgrade_url` - `403 origin_not_allowed` — Origin header doesn't match allowlist - `403 insufficient_scope` — required scope missing; includes `missing` array - `403 feature_not_available` — endpoint requires a higher tier; includes `required_tier` - `404 not_found` - `429 rate_limited` — includes `retry_after_seconds` - `503 db_unavailable` — Cloudflare D1 momentarily unreachable --- ## Widget config shape The resolved widget config returned by `/v1/widget-config/:siteId`: ```json { "fabBg": "#0B1220", "fabIcon": "#D7B98C", "fabBorder": "rgba(184,149,106,0.45)", "accentColor": "#B8956A", "position": "br", "icon": "human", "panelTheme": "auto", "buttons": [ { "key": "font-size", "visible": true, "order": 0 }, { "key": "contrast", "visible": true, "order": 1 }, { "key": "dyslexia", "visible": true, "order": 2 }, { "key": "cursor", "visible": true, "order": 3 }, { "key": "animations", "visible": true, "order": 4 }, { "key": "read-mask", "visible": true, "order": 5 }, { "key": "read-aloud", "visible": true, "order": 6 }, { "key": "simplify", "visible": false, "order": 7 } ], "tier": "free", "showsBanner": true } ``` - `position`: `br` (bottom-right), `bl`, `tr`, `tl` - `icon`: preset name (`human` / `eye` / `wheelchair` / `plus` / `ear` / `star`), raw ``, or single-char emoji - `panelTheme`: `auto` (follow OS), `light`, `dark` - `buttons[*].key`: one of `font-size` / `contrast` / `dyslexia` / `cursor` / `animations` / `read-mask` / `read-aloud` / `simplify` 3-tier inheritance: factory defaults ← user-level config ← site-level config (later wins). --- ## WCAG coverage NAGISOT detects and (where possible) auto-fixes 60+ WCAG 2.2 success criteria: **Level A** (perception, operation): non-text content, audio-only/video-only, captions prerecorded, info and relationships, meaningful sequence, sensory characteristics, use of color, audio control, keyboard, no keyboard trap, timing adjustable, pause stop hide, three flashes, bypass blocks, page titled, focus order, link purpose in context, language of page, on focus, on input, error identification, labels or instructions, parsing. **Level AA** (enhanced perception): captions live, audio description, contrast minimum (4.5:1), resize text, images of text, reflow, contrast non-text (3:1), text spacing, content on hover or focus, multiple ways, headings and labels, focus visible, language of parts, consistent navigation, consistent identification, error suggestion, error prevention legal/financial, status messages, target size minimum. **Level AAA** (currently ~71%): sign language prerecorded, extended audio description, media alternative prerecorded, contrast enhanced (7:1), low or no background audio, visual presentation, images of text no exception, reflow, content on hover or focus, keyboard no exception, no timing, interruptions, re-authenticating, three flashes, location, link purpose link only, section headings, language of parts, unusual words, abbreviations, reading level, pronunciation, change on request, help, error prevention all, target size enhanced, concurrent input mechanisms. --- ## MCP server Planned: `npx @nagisot/mcp` will expose all of `/v1/*` as MCP tools so Claude/Cursor can manage NAGISOT directly from a coding session. --- ## Source-of-truth files in the repo For maintainers / advanced integrators: - `apps/api/src/lib/tiers.ts` — tier limits and feature flags - `apps/api/src/lib/api-keys.ts` — token generation, resolution, scope/origin checks - `apps/api/src/lib/rate-limit.ts` — per-minute (KV) + per-month (D1) quota enforcement - `apps/api/src/routes/v1.ts` — versioned `/v1/*` router + OpenAPI spec - `apps/api/src/routes/public-api-keys.ts` — dashboard endpoints to manage keys - `apps/api/migrations/0010_public_api.sql` — DB schema for the public API - `apps/widget/src/loader.ts` — drop-in script (FAB mount, config fetch, free-tier banner) - `apps/widget/src/widget.ts` — panel renderer (lazy-loaded after FAB click) --- ## License & terms - Commercial license — see https://nagis.doogree.co.il/legal/terms - Privacy policy — https://nagis.doogree.co.il/legal/privacy - Accessibility policy — https://nagis.doogree.co.il/legal/accessibility - Free-tier banner is disclosed in the signup form (required checkbox), the pricing page, and the terms — in that order, not the other way around. --- ## Contact - Email: idanperiyoel@gmail.com - GitHub: https://github.com/idanperiyoel/NAGISUT