API reference

WebmasterID has four distinct surface areas. They use different auth models on purpose — knowing which is which keeps you out of accidental secret-leak territory.

1. Public / browser surface

Safe to ship to every visitor. Uses ONLY the public wm_ id and the public ingest endpoint.

• Tracker script URL: https://webmasterid.com/tracker.iife.min.js (HTTPS, immutable).
• Ingest endpoint: https://webmasterid-ingest-api.vercel.app/api/events (POST, CORS-safe, accepts the event batch payload).
• Public site_id: shape wm_xxxxxxxxxxxxxxxx (16 lowercase base36 chars). Generated when you create a site; safe to embed in HTML.

2. Server-side concepts

Some operators want to record events server-to-server (e.g. post-purchase confirmations from a webhook). The schema accepts a small set of server-side event names (signup, download, app_install_click, lead_submit, template_download, tool_usage, conversion, purchase) authenticated with a hashed server-side secret.

• The hashed secret is stored on the dashboard side; the raw secret is shown to the operator exactly once at site-creation time and never re-displayed.
• The browser snippet on /sites NEVER contains server-side secret material. The agent's create-site / generate-snippet tools also never return it.
• Use only safe placeholders in any docs you write internally.

3. Agent endpoints (dashboard auth)

These live on the operator dashboard. All require a valid dashboard session; unauthenticated requests get HTTP 401 with a JSON body.

• GET /api/agent/manifest — stable, owner-safe orientation manifest. Lists Core modules, conceptual webmasterid-agent modules, the canonical M0–M12 roadmap, the full tool registry, and the locked allowed / approval-required / forbidden actions.
• GET /api/agent/system-state — owner-scoped counts only (active + archived sites, pending + approved drafts, new + reviewing access requests) plus a recommendedAttention list. NEVER returns individual access-request emails or analytics rows.
• GET /api/agent/context — sanitised analytics aggregate for the operator's owned sites. NEVER includes raw IPs, full UAs, or any server-side secret material.
• POST /api/agent/actions — create a reviewable action draft. Sanitiser blocks server-side secret tokens, the secret-hash column name, the database URL env var name, raw IPs, and full UAs before insert.
• POST /api/agent/actions/:id/approve | reject | complete — state transitions. Approval is operator authorisation, not auto-execution.
• POST /api/agent/tools/verify-install — the install probe; returns one of six statuses (see /docs/verify-install).
• POST /api/agent/tools/generate-snippet, generate-campaign-link, generate-install-prompt, generate-improvement-prompt — paste-ready artefact builders for the operator.
• GET /api/reports/context + POST /api/reports/generate — sanitised analytics context + deterministic Markdown generator (no LLM).

4. Health endpoints (public)

• GET https://webmasterid-ingest-api.vercel.app/health — public liveness check on the ingest API. Returns HTTP 200 with {"status":"ok","ts":...}.
• GET https://webmasterid-dashboard.vercel.app/api/health — public liveness check on the dashboard.

Auth model summary

Agent does not control the tracker

Repeat after me: the agent is read-only with respect to analytics collection. The agent has zero endpoints that instruct the tracker to do anything. The orientation manifest explicitly lists this in forbiddenActions: cloaking, fake_ai_traffic, hidden_links, auto_deploy, auto_email, autoposting, ad_review_evasion, doorway_pages, scraping_ai_platforms, ai_system_manipulation, browser_automation_abuse, proxy_rotation, captcha_bypassing, cross_tenant_data_access, auto_user_creation, auto_link_insertion, auto_merge_sites, hard_delete_action_drafts, secret_exposure, weakening_owner_scoping.

Related

• /docs/agent — Core ↔ webmasterid-agent boundary in plain language.
• /architecture — the full system shape.