Embed API

Authentication

Creator routes require an authenticated session cookie. Public API integrations can use creator-issued API keys from the dashboard. Internal cron routes require a bearer secret.

• Public endpoints are rate-limited and should be protected by frontend validation and bot mitigation.
• Admin endpoints require platform-admin scope based on allowlisted accounts.
• Sensitive routes should not be called from unauthenticated client contexts.
• API key management is available at /dashboard/api for paid plans.

Developer API Key Flow

1. Upgrade to a paid creator plan to enable API key generation: Pro ($29.99/mo) or Agency ($79.99/mo).
2. Open /dashboard/api, create a named key, and copy it immediately (shown once).
3. Send keys using X-API-Key or Authorization: Bearer <key>.
4. Track monthly usage per key and revoke compromised keys instantly.

Free plan access remains limited to anonymous public API traffic with stricter limits and no key creation.

API Management Endpoints

• GET /api/developer/keys — List your keys, limits, scopes, and usage snapshots.
• POST /api/developer/keys — Create a key with scopes/origin allowlist/RPM policy.
• PATCH /api/developer/keys — Update key policy (name, scopes, origin allowlist, RPM).
• POST /api/developer/keys/[keyId]/rotate — Rotate active key material (shown once).
• POST /api/developer/keys/[keyId]/revoke — Revoke key immediately.
• GET /api/developer/usage — Creator usage analytics (routes, keys, and monthly totals).
• GET /api/admin/api — Platform-admin API governance overview (traffic/failures/top users).

Scope Model

• public:content.read — Required for content/newsletter public read endpoints.
• public:search.read — Required for public search endpoint usage.
• public:subscribe.write — Required for public subscription POST endpoint usage.
• Scopes are comma-separated per key and enforced per endpoint group.
• Origin allowlists can be configured per key to limit key reuse from unauthorized websites/apps.

Abuse Alerts & Temporary Suspensions

• Abuse checks evaluate burst traffic and high error-rate behavior per key.
• Triggered abuse can place a key in temporary suspended state with expiry and reason metadata.
• Creator alert center: /dashboard/api/alerts (acknowledge/resolve alerts).
• Admin alert center: /dashboard/admin/api/alerts (platform incident triage).
• Admin key controls can manually suspend/reactivate keys and adjust policy controls.

Core Routes

• POST /api/newsletters — Create a newsletter engine.
• GET /api/dashboard/overview — Load creator dashboard stats and draft campaigns.
• GET/PATCH /api/campaigns/[campaignId] — Load and save editor campaigns.
• POST /api/campaigns/[campaignId]/send — Dispatch a campaign to active subscribers.
• POST /api/public/subscribe — Public subscription endpoint for hosted pages.
• GET/PATCH /api/public/preferences/[subscriberId] — Subscriber self-serve preference endpoint.
• GET /api/system/readiness — Environment and persistence readiness check for deployments.
• GET/PATCH /api/admin/operations — Admin-only operational controls and audit view.

AI & Content Routes

• POST /api/ai/suggestions — Input copy, help answer, website copy, and content draft generation.
• POST /api/campaigns/[campaignId]/regenerate — Regenerate campaign HTML with instruction prompts.
• POST /api/campaigns/[campaignId]/subject — Generate subject lines based on campaign HTML.
• POST /api/ai/training — Save manual training signals and ingest knowledge context.
• POST /api/ai/ingest-site — Crawl sitemap-based content for contextual grounding.

Website & Platform Integrations

• Custom sites: use a direct CTA button linking to /p/[slug] near hero, sidebar, and article footer.
• WordPress: place subscribe button or widget via Gutenberg Custom HTML or shortcode.
• Shopify: embed newsletter CTA in theme snippet/section for homepage and blog templates.
• API integration: POST /api/public/subscribe from your own form handlers for custom UX.
• Feed embedding: GET /api/public/content?type=community&sourceNewsletterSlug=[slug] for newsletter-scoped community feeds.
• Preference center: link subscriber actions to /preferences/[subscriberId] for self-service controls.

Rate Limits

Public and authentication endpoints are rate-limited. API-key traffic supports per-key RPM controls and monthly metering by key. Production deployments should still add edge-level bot filtering and WAF controls for layered protection.

Role Boundaries

• Platform Admin APIs are restricted to allowlisted admin accounts only.
• Newsletter team admins are newsletter-scoped collaborators and do not inherit platform-admin powers.
• Keep admin automation and newsletter automation separate in your tooling and access tokens.

Request Quality & Validation

• Send JSON payloads with explicit required fields and trimmed values.
• Always handle non-200 responses and show actionable UI notices to users.
• Use retry logic only for transient failures; do not retry validation or authorization errors.
• For send flows, enforce policy acceptance and unsubscribe-token presence checks in the editor.

Operational Notes

• Set ADMIN_EMAILS to a comma-separated allowlist for admin account assignment.
• Run npm run readiness before release and after infrastructure changes.
• Use CI checks (lint, typecheck, build) as a required merge gate.
• Verify domain DNS, sender profile, and provider credentials before enabling production campaigns.
• Review Terms/Privacy pages on policy updates and keep internal workflows aligned.