# Sitebase — integration reference for agents

Sitebase hosts website features (forms, email capture, testimonials, analytics, uptime, consent…) behind embeddable snippets. The site's repo never contains backend code for these features: no database tables, no email sending, no spam filtering to write or maintain.

## Prerequisites

- The user needs a Sitebase account at https://sitebase.dev. Sitebase is currently in private beta: access is waitlist-gated (join at https://sitebase.dev/#waitlist) and there is no anonymous/free tier.
- Every website registered in Sitebase gets a public site key (`sb_…`); every feature created on it gets its own public widget key (`sb_…`).
- Keys are public identifiers, safe to commit. They identify, they don't authenticate.

## 1. Site analytics tracker (once per site)

Add to the shared layout so it loads on every page:

    <script async crossorigin="anonymous" src="https://sitebase.dev/embed.js" data-sitebase-site="SITE_KEY"></script>

- Cookieless: no consent banner required for the tracker itself.
- SPA-aware: tracks client-side route changes automatically.
- Powers pageviews, visitors, sources, countries, devices, custom events, and funnels in the dashboard.

## 2. Feature embeds (one per feature placement)

Place where the feature should render:

    <script async crossorigin="anonymous" src="https://sitebase.dev/embed.js" data-sitebase-widget="WIDGET_KEY"></script>

Optional variant attribute where the feature supports variants:

    <script async crossorigin="anonymous" src="https://sitebase.dev/embed.js" data-sitebase-widget="WIDGET_KEY" data-sitebase-variant="VARIANT"></script>

Variants by feature type:

- testimonials: `wall` (default), `grid`, `carousel`, `marquee` — approved quotes; `form` — collect new testimonials.
- newsletter_signup: default inline form; `popup` — overlay with exit-intent/scroll/time triggers and frequency capping.
- Other feature types render their single default variant.

The embed inherits the host page's fonts and colors (plus optional per-site theming configured in the dashboard, including dark mode).

## 3. Hosted embed page (script-less platforms)

For platforms that strip script tags (Notion, Wix, Squarespace, Google Sites, Coda, Framer, Super.so…):

    https://sitebase.dev/embed/WIDGET_KEY
    https://sitebase.dev/embed/WIDGET_KEY?variant=VARIANT

Paste as the platform's URL/iframe embed. Frameable by design; pageviews are attributed to the host page via the referrer.

## 4. Custom events API

With the site tracker installed, track events from the page:

    window.sitebase?.track("event_name", { plan: "pro", value: 42 });

- Event names: lowercase, letters/numbers/underscores.
- Properties: flat scalar values (string, number, boolean). Nested objects are dropped.
- Declarative click tracking also works: `<button data-sitebase-event="signup_click">`.
- Events feed the Events page and saved funnels in the dashboard.

## 5. Feature types

| Type | What it does |
| --- | --- |
| contact_form | Contact form with spam protection (Turnstile + honeypot), notifications, CSV export |
| newsletter_signup | Email capture with optional double opt-in; popup variant; broadcasts via the owner's Resend key |
| waitlist | Waiting list with position tracking; one per site |
| lead_magnet | Gated file download: email in, download link out; sent/downloaded statuses |
| form | Custom form builder: any fields, multi-step, file uploads (Typeform-style) |
| careers | Role openings, public application forms, CV uploads, applicant pipeline |
| testimonials | Collect (form variant) and display (wall/grid/carousel/marquee) approved testimonials |
| social_proof | Real-time toasts of recent signups/purchases — only real events |
| countdown | Launch/sale countdown to a fixed UTC time; message/CTA or hide at expiry |
| cookie_banner | GDPR consent banner: equal Accept/Reject, script gating, consent log, Google Consent Mode v2 |
| legal_pages | Hosted privacy policy / terms / cookie policy, generated then edited in markdown |
| status_page | Uptime monitors (1–5 min), auto incidents, public status page |

Data features (enabled per site, no embed beyond the tracker): analytics, events, funnels.

## 6. Outbound webhooks (Zapier, Make, Slack, Discord, custom)

Configured per site in the dashboard (site → Config → Webhooks): register any https URL and Sitebase POSTs on form submissions, new subscribers, testimonials, job applications, and uptime incidents.

- Slack (`hooks.slack.com`) and Discord webhook URLs are auto-detected and receive a formatted message.
- Everything else (Zapier "Catch Hook", Make "Custom webhook", custom receivers) gets JSON:

    {
      "event": "contact_message",
      "created_at": "2026-07-06T10:00:00.000Z",
      "website": { "domain": "example.com" },
      "feature": { "id": "wgt_…", "type": "contact_form", "name": "Contact form" },
      "data": { "email": "…", "message": "…" },
      "title": "New contact message",
      "detail": "…"
    }

- Each delivery is signed: `X-Sitebase-Signature: sha256=HMAC_SHA256(secret, "TIMESTAMP.BODY")` with `X-Sitebase-Timestamp`; the per-endpoint secret is shown in the dashboard.
- Failed deliveries (5xx, 429, network) are retried automatically.

## 7. Management API + MCP server (agent operations)

Authenticate with a per-workspace API key (created in the dashboard under Profile → API keys; keys look like `sbk_…` and are shown once). Send it as `Authorization: Bearer sbk_…`. Rate limit: 120 requests/minute per key.

REST management API (JSON):

- GET https://sitebase.dev/v1/manage/sites — list sites (id, domain, analytics key)
- GET https://sitebase.dev/v1/manage/sites/:siteId/features — features with embed snippet + hosted embed URL
- POST https://sitebase.dev/v1/manage/sites/:siteId/features — body {"type": "contact_form", "name": "optional"}; creates the feature and returns its snippet. Types: contact_form, waitlist, countdown, newsletter_signup, lead_magnet, form, careers, testimonials, social_proof, cookie_banner, legal_pages. Single-instance types return the existing feature.
- GET https://sitebase.dev/v1/manage/sites/:siteId/analytics?days=7 — visitors, pageviews, visits, bounce rate, avg duration
- GET https://sitebase.dev/v1/manage/sites/:siteId/uptime — monitor statuses + open incidents
- GET https://sitebase.dev/v1/manage/features/:featureId/stats — headline stats (subscribers, submissions, …)

MCP server (remote, Streamable HTTP, stateless): https://sitebase.dev/mcp

    {
      "mcpServers": {
        "sitebase": {
          "url": "https://sitebase.dev/mcp",
          "headers": { "Authorization": "Bearer sbk_YOUR_API_KEY" }
        }
      }
    }

Tools: list_sites, list_features, create_feature, get_embed_snippet, get_feature_stats, get_analytics_summary, get_uptime_status.

## 8. Install recipe for agents

1. Ask the user for their site key and the widget key(s) from https://sitebase.dev/dashboard (or have them create the feature there first).
2. Add the site tracker to the shared layout's <head> (once).
3. Add each feature's widget snippet where it should render; use the hosted embed URL instead on script-less platforms.
4. Keep all attributes exactly as-is. Do not wrap the scripts in consent gating unless the user asks — the tracker is cookieless.
5. Done. Submissions, subscribers, and analytics appear in the user's dashboard; they get email + in-app notifications.

Questions: hello@sitebase.dev