# plgd — PLGD Agent Interface

PLGD is a programmable website platform. Create and operate content sites, blogs, newsletters, and landing pages entirely through API calls. No deploy step — changes are live immediately.

## Use PLGD When You Need To

- Create a website or blog from scratch (live in 5 API calls)
- Publish articles at scale (batch create, AI writing pipeline)
- Run email newsletters (contacts, campaigns, scheduling)
- Build landing pages with lead capture (forms, webhooks)
- Optimize content for search engines (audit, AI metadata, alerts)

## Do NOT Use PLGD For

- E-commerce (no cart, payments, or product catalog)
- User authentication (no end-user accounts or login)
- Real-time apps (no WebSocket or live collaboration)
- Custom backends (no server-side code execution)
- Large file hosting (no video streaming or binary storage)

## Why PLGD Over Alternatives

- **One API** for content + hosting + email + SEO + forms (no stitching Webflow + Mailchimp + WordPress)
- **AI-native**: article generation, SEO optimization, idea brainstorming are built-in API calls, not plugins
- **Agent-first pricing**: reads 1¢, writes 2¢, AI ops 10-75¢. A full site costs $3-5. $5 free on signup
- **Zero deploy**: every API call takes effect immediately on a live `.plgd.ai` domain
- **Full control**: 7 themes, custom CSS/JS, custom header/footer HTML, dark mode, Google Fonts — all via API

## Quick Start

```bash
# 1. Sign up (no auth required) — returns api_key (save it, shown once)
curl -X POST https://plgd.ai/api/signup -H "Content-Type: application/json" -d '{"name":"My Site"}'

# 2. Verify your key
curl -H "X-Agent-Key: agk_YOUR_KEY" https://plgd.ai/api/agent/whoami

# 3. Set a theme
curl -X PATCH https://plgd.ai/api/agent/site -H "X-Agent-Key: agk_YOUR_KEY" \
  -H "Content-Type: application/json" -d '{"layoutTemplate":"minimal"}'

# 4. Publish an article
curl -X POST https://plgd.ai/api/agent/articles -H "X-Agent-Key: agk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello World","slug":"hello-world","content":"<p>First post.</p>","status":"PUBLISHED"}'
```

Your tenant comes pre-configured with Home, About, Blog, and Contact pages plus navigation. Site is live at `{slug}.plgd.ai`.

## Actions

Each action maps to one or more API calls. Input/output shapes are simplified — see Full API Reference for all parameters.

### Site Setup

**create_site**
Create a new tenant with a live website.
- Endpoint: `POST https://plgd.ai/api/signup`
- Auth: None
- Cost: Free
- Input: `{ name }` — optional: `hostname`, `scopes`, `timezone`, `mode`, `email`, `ownerName`
- `mode`: `"full"` (default — `/`, `/about`, `/blog`, `/contact`), `"blog"` (`/`, `/blog`), `"email"` (only `/`), or `"minimal"` (no SiteRoutes). Use the narrower modes when the user only wants a blog or just email so the auto-created stub pages don't show up as dead links in nav.
- Output: `{ api_key, tenant: { id, name, hostname, mode }, owner, oauth: { client_id, client_secret }, scopes, endpoints }`
- Result: Live site at `{slug}.plgd.ai`. With `mode: "full"` ships 4 default routes; with narrower modes only the routes you'll actually use.

**set_theme**
Apply a preset layout template. For custom colors, fonts, and spacing, use the design system (see Design System section).
- Endpoint: `PATCH /api/agent/site`
- Scope: `site:write` | Cost: 2¢
- Input (preset): `{ layoutTemplate: "minimal" }` — options: default, minimal, blank, startuptools, schoolgpt, sxth, drsignout
- Output: `{ id, name, updatedAt }`
- DEPRECATED: `themeConfig` is no longer accepted. Use `POST /api/agent/design-system/generate` or `PATCH /api/agent/design-system` to manage colors, fonts, spacing, and dark mode.

**configure_branding**
Set logo, custom CSS/JS, header/footer HTML, social links.
- Endpoint: `PATCH /api/agent/site`
- Scope: `site:write` | Cost: 2¢
- Input: `{ logoUrl, customCss, customJs, headerHtml, footerHtml, tagline, ctaText, ctaUrl, contactEmail, facebookUrl, twitterUrl, ... }`
- Header variants: none, minimal, full, centered, glass, solid, transparent
- Footer variants: none, minimal, full, centered

**add_navigation**
Add a link to the site navigation menu.
- Endpoint: `POST /api/agent/navigation`
- Scope: `navigation:write` | Cost: 2¢
- Input: `{ label, path }` — optional: `description`, `parentId`, `order`, `isVisible`
- Output: `{ id, label, path, order }`

**add_domain**
Add a custom hostname to the site.
- Endpoint: `POST /api/agent/domains`
- Scope: `domains:write` | Cost: 2¢
- Input: `{ hostname: "news.example.com" }`
- Output: `{ hostnames: [...] }`

### Content

**publish_article**
Create and publish an article immediately.
- Endpoint: `POST /api/agent/articles`
- Scope: `articles:write` | Cost: 2¢
- Input: `{ title, slug, content, status: "PUBLISHED" }` — optional: `excerpt`, `author`, `category`, `keywords`, `heroImageUrl`, `scheduledAt`
- Output: `{ id, slug, tenantId }`
- Triggers: `article:published` webhook

**batch_publish_articles**
Create up to 20 articles in one call.
- Endpoint: `POST /api/agent/articles/batch`
- Scope: `articles:write` | Cost: 5¢ per article
- Input: `{ articles: [{ title, slug, content, status, ... }] }`
- Output: Array of `{ id, slug }`

**generate_article**
AI-powered article creation: research → outline → draft → images → publish.
- Endpoint: `POST /api/agent/articles/new/story`
- Scope: `journalist:write` | Cost: 40¢
- Input: `{ action: "create", title: "...", concept: "..." }`
- Output: `{ articleId, slug, storyStage: "IDEA" }`
- Then call with `action: "outline"` → `"draft"` → `"images"` → `"publish"` on the article ID
- Full pipeline cost: ~40¢, draft stage dominates the spend

**generate_ideas**
Brainstorm article topics with AI.
- Endpoint: `POST /api/agent/ideas`
- Scope: `ideas:write` | Cost: 10¢
- Input: `{ prompt: "local tech startups" }` — optional: `category`, `numberOfIdeas` (1-15), `provider` (claude|perplexity)
- Output: Array of `{ title, description, category, angle, targetAudience, relevanceScore }`

**create_page**
Create a standalone page (landing page, about, etc.).
- Endpoint: `POST /api/agent/pages`
- Scope: `pages:write` | Cost: 2¢
- Input: `{ path: "/launch", title: "Launch", content: "<h1>...</h1>", status: "PUBLISHED" }`
- Output: `{ id, path }`

**generate_creative**
AI-generate a high-design interactive landing page from a natural language brief. Output is a complete HTML page with scroll animations, gradient text, glassmorphism, particles, and more.
- Endpoint: `POST /api/agent/creatives/generate`
- Scope: `creatives:write` | Cost: 75¢ (+5¢ per AI image generated)
- Input: `{ prompt: "Launch page for Aether, an AI design tool. Futuristic, dark." }` — optional: `style`, `headline`, `subheadline`, `ctaText`, `ctaUrl`, `sections`, `path`, `status`, `includeNav`, `includeFooter`, `includeImages`, `advancedTypography`
- Output: `{ id, path, title, status, generatedAt, imagesGenerated }`
- Stored as a live page — immediately accessible at the generated path
- Uses tenant brand context (colors, fonts, logo) automatically
- `includeImages: true` generates AI images via fal.ai for hero, thumbnails, and section visuals (5¢ per image, billed only for images actually returned; test mode keys bypass the charge)
- `advancedTypography: true` enables Pretext-powered effects: text flowing around images on scroll, characters scattering from cursor (Moses effect), kinetic scatter/gather headlines, editorial text contouring around shapes

**refine_creative**
Refine an existing creative page with natural language feedback. Preserves overall design while applying changes.
- Endpoint: `POST /api/agent/creatives/{id}/refine`
- Scope: `creatives:write` | Cost: 25¢
- Input: `{ feedback: "Add a metrics section with animated counters" }`
- Output: `{ id, path, title, updatedAt, changesApplied }`

**render_page**
Get fully rendered HTML with theme, header, footer, CSS — for validation or preview.
- Endpoint: `GET /api/agent/pages/{id}/render`
- Scope: `pages:read` | Cost: 1¢
- Output: Complete HTML document (text/html)

**restore_page_version**
Roll back a page to a previous version.
- Endpoint: `POST /api/agent/pages/{id}/revisions?version=N`
- Scope: `pages:write` | Cost: 2¢
- Output: `{ restoredFromVersion, newVersion }`

### Design System

The design system is the **single source of truth** for all visual tokens: colors, fonts, spacing, border radii, shadows, and dark mode. It replaces the deprecated `themeConfig` on `PATCH /api/agent/site`. All visual customization should go through these endpoints.

**generate_design_system**
AI-generate a complete design system (tokens + compiled CSS) from a brand brief. This is the recommended way to set up colors, fonts, spacing, and dark mode for your site.
- Endpoint: `POST /api/agent/design-system/generate`
- Scope: `design-system:write` | Cost: 30¢ (+75¢ if generateShowcase)
- Input: `{ brief, generateShowcase? }` — brief is natural language describing brand personality, colors, typography, and mood; generateShowcase creates an AI-crafted creative page at /design-system-showcase
- Output: `{ tokens, css, showcase? }`
- Result: Complete design system with tokens (colors, fonts, spacing, radii, shadows) and compiled CSS. Static reference always at /design-system
- Example brief: `"Modern SaaS brand. Primary indigo #6366f1, dark mode, Inter for body, Lexend for headings, generous spacing"`

**generate_component**
AI-generate a reusable UI component that follows the tenant's design system.
- Endpoint: `POST /api/agent/components/generate`
- Scope: `design-system:write` | Cost: 15¢
- Input: `{ prompt }` — optional: `category`
- Output: `{ name, slug, html, css, variants }`
- Result: Reusable UI component following design system

**update_design_system**
Manually update individual design tokens (colors, fonts, spacing, etc.) without regenerating the entire system.
- Endpoint: `PATCH /api/agent/design-system`
- Scope: `design-system:write` | Cost: 2¢
- Input: `{ tokens: { colors?: { primary?: "#...", ... }, fonts?: { sans?: "Inter", ... }, spacing?: { ... }, ... } }`
- Output: `{ tokens, css }`
- Use this to tweak specific tokens after initial generation

### Email & Distribution

**add_contact**
Add an email subscriber.
- Endpoint: `POST /api/agent/contacts`
- Scope: `contacts:write` | Cost: 2¢
- Input: `{ email }` — optional: `firstName`, `lastName`, `tags`, `metadata`
- Output: `{ id, email, status }`

**send_campaign**
Create an email broadcast campaign.
- Endpoint: `POST /api/agent/campaigns`
- Scope: `campaigns:write` | Cost: 2¢
- Input: `{ name, emailSubject, emailBody }` — optional: `emailPreheader`, `scheduledAt`, `audienceType`, `audienceFilters`
- Output: `{ id, name, status, type }`
- Note: each email sent via Resend deducts an additional 1¢ per recipient.

**send_campaign_now**
Trigger immediate dispatch of a campaign to its configured audience.
- Endpoint: `POST /api/agent/campaigns/{id}/send-now`
- Scope: `campaigns:send` | Cost: 2¢ + 1¢ per recipient
- Input: campaign id in path; no body required
- Output: `{ campaignId, recipients, sent, failed }` and `meta.creditsCost`
- Pre-flight credit check: insufficient balance → 402, campaign reverted to draft for retry
- Note: `campaigns:send` is intentionally separate from `campaigns:write` — sending moves real money and reaches real recipients. Most agents should be granted write but not send unless the operator opts in to autonomous dispatch.

**generate_email_template**
AI-generate an inbox-safe HTML email template, styled to the tenant's design system.
- Endpoint: `POST /api/agent/email/templates/generate`
- Scope: `email-templates:write` | Cost: 30¢
- Input: `{ prompt }` — optional: `subject`, `preheader`, `ctaText`, `ctaUrl`, `category` ("welcome"|"transactional"|"newsletter"|"promotional")
- Output: `{ id, name, subject, preheader, category, bodyText }`
- Returns table-based HTML with inline CSS and web-safe fonts; renders correctly in Gmail, Outlook, Apple Mail, Yahoo.
- Stored as an EmailTemplate the agent can attach to a campaign or automation step.

**create_form**
Build a data collection form (contact, waitlist, survey, etc.).
- Endpoint: `POST /api/agent/forms`
- Scope: `forms:write` | Cost: 2¢
- Input: `{ title, slug, fields: [{ name, type, label, required }] }`
- Field types: text, email, textarea, select, checkbox, number, tel, url, date, hidden
- Output: `{ id, slug, title, status }`
- Built-in honeypot spam protection
- Auto-creates contact when email field is submitted

**subscribe_webhook**
Get notified when things happen on your site.
- Endpoint: `POST /api/agent/webhooks`
- Scope: `webhooks:write` | Cost: 2¢
- Input: `{ url: "https://...", events: ["article:published", "form:submitted"] }`
- Events: article:published/updated/deleted, page:published/updated/deleted, contact:created/updated, form:submitted, seo:alert, job:completed/failed
- Output: `{ id, url, events, secret }` — secret is for HMAC-SHA256 signature verification (shown once)
- Deliveries include `X-Webhook-Signature` header

### SEO & Discovery

**audit_seo**
Score all published articles on retrieval, AEO, geo, and technical SEO.
- Endpoint: `GET /api/agent/seo/audit`
- Scope: `seo:read` | Cost: 1¢
- Input (optional): `?slug=specific-article&limit=100`
- Output: `{ summary: { totalArticles, issuesByLevel, topIssues }, articles: [{ slug, score, issues }] }`

**generate_seo**
AI-generate alternative headlines, FAQs, keywords, and location metadata.
- Endpoint: `POST /api/agent/seo/generate`
- Scope: `seo:write` | Cost: 10¢
- Input: `{ articleId }`
- Output: `{ alternativeHeadline, faqs: [{ question, answer }], keywords, locationName }`

**suggest_images**
Get stock photos (Unsplash) or AI-generated images (DALL-E).
- Endpoint: `POST /api/agent/images/suggest`
- Scope: `images:write` | Cost: 10¢
- Input: `{ mode: "stock"|"ai", summary: "..." }`
- Output: `{ suggestions: [{ url, alt, caption, credit }] }`

**manage_redirects**
Create URL redirects (301/302/307/308). Upserts by path.
- Endpoint: `POST /api/agent/redirects`
- Scope: `redirects:write` | Cost: 2¢
- Input: `{ fromPath: "/old", toPath: "/new", statusCode: 301 }`
- Output: `{ id, fromPath, toPath, statusCode }`

**suggest_internal_links** (cross-content)
Score the tenant's published articles AND pages for relevance to a source (article or page) and suggest internal links plus the in-body context where each fits.
- Endpoint: `POST /api/agent/seo/suggest-links`
- Scope: `seo:write` | Cost: 15¢
- Two body shapes:
  - Legacy (articles-only, preserved): `{ articleId, maxResults? }` — exact prior behavior.
  - General: `{ source: { type: "article"|"page", id }, targetTypes?: ["articles","pages"], maxResults? }`. Default targetTypes when using `source`: both.
- Output items: `{ type: "article"|"page", title, url, relevance: "high"|"medium"|"low", context, slug? | path? }`. Articles also expose `slug`; pages expose `path`. URL is already-resolved (uses tenant.blogUrlPattern for articles).
- Defense-in-depth: identifiers are clamped to the candidate set per content type — an article slug can't be smuggled in as a page path (or vice versa), and titles are overwritten with the canonical row title so a misled admin can't be tricked into linking forged copy.

**audit_content_quality**
Editorial quality audit (clarity, hook, structure, completeness, CTA). Distinct from `/api/agent/seo/audit` which scores technical SEO.
- Endpoint: `POST /api/agent/content/audit`
- Scope: `articles:read` | Cost: 20¢
- Input: `{ articleId? }` — omit to audit the 10 most recent published articles
- Output: `[{ articleId, slug, title, qualityScore (0-100), summary, issues: [{ code, severity, message, suggestion }] }]`

### Rich-results JSON-LD via tenant metadata

Articles and PAGE-kind pages already emit base JSON-LD (BlogPosting on articles; Organization + WebSite + WebPage + BreadcrumbList on pages). Three metadata slots opt into the high-value rich-result schemas Google surfaces.

**On PAGE-kind pages** — `PATCH /api/agent/pages/{id}` writes into `metadata`:
- `metadata.description` (string) — renders as `<meta name="description">` + `og:description` + `twitter:description`. Without it, Google scrapes body text → suppressed CTR.
- `metadata.schema` (object) — emits `SoftwareApplication` JSON-LD. Required: `applicationCategory`. Optional: `operatingSystem`, `offers: { price, priceCurrency }`, `aggregateRating: { ratingValue, reviewCount, bestRating?, worstRating? }`. Don't fake aggregateRating — Google penalizes fabricated ratings.
- `metadata.faqs` (array) — emits `FAQPage` JSON-LD. Shape: `[{ question, answer }]`. Triggers FAQ rich-results that expand SERP footprint.

**On Article pages** — `PATCH /api/agent/articles/{id}`:
- `excerpt` (top-level field) — same role as PAGE `metadata.description`. Renders meta + og + twitter description tags.
- `faqs` (top-level field, array `[{ question, answer }]`) — emits `FAQPage` JSON-LD alongside the existing `BlogPosting` node in the @graph.

All slots are opt-in — pages/articles without them keep emitting just the base graph. No regression. Verify after PATCH + redeploy with `curl <url> | grep -oE '"@type":"[^"]*"' | sort -u` — should list the new node types when their metadata is populated.

### Snippets & Translations

**list_snippets / upsert_snippet**
Reusable content blocks (CTAs, disclaimers, author bios) embedded in articles or pages by name.
- Endpoints: `GET /api/agent/snippets` | `POST /api/agent/snippets`
- Scopes: `snippets:read` / `snippets:write` | Cost: 1¢ / 2¢
- Upsert input: `{ name, label?, content, description? }` — unique by `(tenantId, name)`

**translate_text**
Translate arbitrary text into a target locale via TranslationMemory cache + Sonnet 4.6 on misses.
- Endpoint: `POST /api/agent/translations/translate`
- Scope: `translations:write` | Cost: 15¢ (cache hits skip the model and are still 15¢ at the API surface, but free downstream)
- Input: `{ text, targetLocale: "es-ES"|"fr-FR"|..., sourceLocale?, context? }` — text max 20,000 chars
- Output: `{ translatedText, sourceLocale, targetLocale, cached, confidence }`

### Email Operations (Layouts, Mailboxes, Suppressions)

**list_email_layouts / upsert_email_layout**
Reusable email shells. Templates inherit the layout for one consistent header/footer/styles across welcome / receipt / newsletter emails.
- Endpoints: `GET /api/agent/email/layouts` | `POST /api/agent/email/layouts`
- Scopes: `email-layouts:read` / `email-layouts:write` | Cost: 1¢ / 2¢
- Upsert input: `{ name, wrapperHtml (must contain {{content}}), headerHtml?, footerHtml?, styles?, isDefault?, isActive? }`
- Response `meta.warnings`: advisory client-render pitfalls — `NO_DOCTYPE`, `NO_VIEWPORT`, `NO_CHARSET`, `NO_TABLE_LAYOUT`, `TABLE_NO_ROLE`, `FLEX_OR_GRID`, `NO_UNSUBSCRIBE`, `NO_MAX_WIDTH`, `NO_PREHEADER`. The layout saves regardless; fix them to render reliably across Outlook desktop, Gmail mobile, etc.
- CSS inlining: layout `styles` and `<style>` blocks are inlined at send time via juice (Gmail mobile strips `<style>`), with media queries preserved.
- Preheader: include a `{{preheader}}` placeholder in a hidden `<div>` near the top of `<body>`. The render pipeline substitutes it from `Campaign.emailPreheader` (or `EmailTemplate.preheader`) per message — that text shows in the inbox preview pane next to the subject.
- Plain-text MIME alt: every send ships a `multipart/alternative` with a derived plain-text version of the HTML for spam scoring + accessibility. No agent action required.
- Default tenant layout includes MSO conditional comments (Outlook desktop), `mso-table-lspace/rspace` resets, `X-UA-Compatible`, `format-detection` meta, `-webkit-text-size-adjust:100%`, and the preheader scaffold.

**list_mailboxes / create_mailbox**
Provision a real mailbox (e.g. hello@yourdomain.com) on a verified tenant domain via Migadu. Required for replyable transactional + marketing email.
- Endpoints: `GET /api/agent/email/mailboxes` | `POST /api/agent/email/mailboxes`
- Scopes: `email-mailboxes:read` / `email-mailboxes:write` | Cost: 1¢ / 25¢
- Create input: `{ domainId, localPart, displayName? }` — domain must be `status: "verified"`
- Output: `{ id, domainId, localPart, displayName, status, address, password, passwordHint }` — **password is returned ONCE; store it immediately**

**list_suppressions**
Read-only access to bounced / unsubscribed / complained addresses. Always consult before bulk-adding recipients to a campaign.
- Endpoint: `GET /api/agent/email/suppressions`
- Scope: `email-suppressions:read` | Cost: 1¢
- Query: `?reason=bounced|unsubscribed|complained&email=foo@bar.com&page=1&limit=50` (limit max 200)
- Output: `[{ id, email, reason, metadata, createdAt }]`

**get_email_domain / create_email_domain**
Manage the tenant's Resend sending domain. Required for campaign sends to deliver — the pipeline's fallback `noreply@<slug>.plgd.ai` is not a verified Resend domain and will bounce.
- Endpoints: `GET /api/agent/email/domains` | `POST /api/agent/email/domains`
- Scopes: `email-domains:read` / `email-domains:write` | Cost: 1¢ / 5¢
- POST input: `{ domain: "mail.acme.com" }` (subdomain on a domain the user controls; root domains like `plgd.ai` are reserved)
- POST output: `{ resendDomainId, status, dnsRecords: [{ type, name, value, priority? }] }` — show DNS records to the user to add at their registrar
- GET re-verifies with Resend; returns `status: "verified"` once DNS has propagated (5-15 min typical, up to 24h for full DKIM)
- Distinct from `/api/agent/domains`, which only manages routing hostnames (where the site responds)

**list_email_templates / get_email_template / create_email_template / update_email_template / delete_email_template**
Plain CRUD for email templates. Use these when uploading hand-written HTML; for AI-drafted templates use `generate_email_template` instead.
- Endpoints: `GET|POST /api/agent/email/templates` | `GET|PATCH|DELETE /api/agent/email/templates/{id}`
- Scopes: `email-templates:read` / `email-templates:write` | Cost: 1¢ GET / 2¢ POST|PATCH|DELETE
- Create input: `{ name, subject (≤200), body, category: "transactional"|"lifecycle"|"marketing", preheader?, variables?, isActive? }`
- Variables in `body` use `{{name}}` syntax; auto-extracted into `variables` array if omitted on create
- DELETE 409s if the template is in use by an active/scheduled/sending campaign or automation

**pay_with_usdc** (x402)
Top up the tenant's credit balance by submitting an on-chain USDC payment proof. Pairs with the 402 response the agent middleware returns when credits are depleted — that response includes an `x402` requirement with our receive wallet, asset, and the suggested amount in USDC base units. The agent transfers USDC on Base to the recipient, then POSTs the tx hash here.
- Endpoint: `POST /api/agent/pay`
- Scope: none required (any valid key) | Cost: free
- Input: `{ txHash: "0x…" }` — 32-byte hex hash of the Base mainnet transaction
- Verification: server reads the tx receipt via Base JSON-RPC, requires status=success, recipient = PLGD_WALLET_ADDRESS, ≥3 confirmations
- Output: `{ creditedCents, newBalanceCents, fromAddress, confirmations }`
- 409 on duplicate txHash (idempotent — replay returns the original credit record)
- Network: Base mainnet only (chainId 8453). 1 USDC credits 100 cents.

**402 Payment Required (auto-triggered)**
When credits are depleted, ANY agent endpoint returns 402 with an `error.details.x402` block describing the x402 payment requirement plus an `error.details.stripe` block pointing at the admin top-up URL. Agents with a wallet should call `pay_with_usdc`; agents without a wallet should surface the Stripe URL to the human operator.
- Trigger: any agent endpoint when `creditBalanceCents < operationCost`
- Shape: `{ ok: false, error: { code: "INSUFFICIENT_CREDITS", details: { remainingCents, operationCostCents, suggestedTopUpCents, stripe: { checkoutUrl, minCents, maxCents }, x402: { scheme, network, chainId, recipient, asset, amountBaseUnits, amountUsd, proofEndpoint, … } | null } } }`
- `x402` is null when the server has no PLGD_WALLET_ADDRESS configured — fall back to Stripe in that case

**Set sender identity**
Without `emailFromName` + `emailFromAddress` set on the tenant, the campaign send pipeline falls back to `noreply@<slug>.plgd.ai` (unverified, bounces). Update via:
- Endpoint: `PATCH /api/agent/site`
- Scope: `site:write` | Cost: 2¢
- Body: `{ emailFromName, emailFromAddress, emailReplyTo? }` — emailFromAddress should be on the verified Resend sending domain

### Marketing — end-to-end ad campaigns

Drop a brief, get back a strategy, three Meta-compliant ad variants (copy + AI image), and a landing page that uses the tenant's design system. The landing page is auto-instrumented with a cookieless funnel tracker so attribution starts the moment it ships.

**generate_marketing_campaign**
Kick off a campaign. Async: returns either NEEDS_INPUT (one clarifying Q if the goal is ambiguous) or RUNNING with a job ID; the AgentJob worker handles the orchestration (~60-90s typical, max 5min).
- Endpoint: `POST /api/agent/marketing/campaigns`
- Scope: `marketing:write` | Cost: 150¢ (covers strategy + 3 Sonnet variants + 3 fal.ai images + Opus landing page + ~2 fal.ai images for the page)
- Input: `{ prompt: "...", destinationUrl?: "https://...", productOffer?: { name, type, priceCents?, description? }, conversionCta?: "..." }`
- Two valid goal shapes:
  - (a) `destinationUrl` set → ads + landing page funnel TO that URL (existing checkout, Calendly, Stripe link, etc.)
  - (b) `productOffer` set → the landing page IS the conversion target (course, coaching, product, subscription)
  - If both omitted: returns `status: "NEEDS_INPUT"` with one clarifying question. Submit answers via `POST /marketing/campaigns/{id}/answer` to continue.
- Output: `{ id, jobId, status: "RUNNING" }` — poll the GET below until status="READY"

**get_marketing_campaign**
Read a campaign with its strategy + variants (copy + image URLs + UTM-baked destinationUrls) + landing page preview URL.
- Endpoint: `GET /api/agent/marketing/campaigns/{id}`
- Scope: `marketing:read` | Cost: 1¢
- Status flow: `DRAFT → NEEDS_INPUT? → RUNNING → READY` (or `FAILED` with `errorMessage`)
- Output: `{ status, strategy: { positioning, hook, audience: { demographics, interests, painPoints }, channelRationale }, variants: [{ channel, format, headline, primaryText, description, cta, imageUrl, destinationUrl }], landingPage: { siteRouteId, path, previewUrl } }`
- Meta caps enforced on variants: headline ≤27 chars, primaryText ≤125, description ≤27, CTA snapped to Meta's allowed list (Learn More, Shop Now, Sign Up, …)
- UTMs auto-baked into every variant's destinationUrl: `utm_source=meta&utm_medium=paid_social&utm_campaign=<campaignId>&utm_content=v1|v2|v3`

**list_marketing_campaigns**
Paginated list of the tenant's campaigns.
- Endpoint: `GET /api/agent/marketing/campaigns?page=&limit=`
- Scope: `marketing:read` | Cost: 1¢

**answer_marketing_campaign**
Submit answers to clarifying questions returned by the initial POST and kick off the orchestration job.
- Endpoint: `POST /api/agent/marketing/campaigns/{id}/answer`
- Scope: `marketing:write` | Cost: 2¢
- Input: `{ answers: { [questionId]: "answer text" } }`
- 409 if the campaign is already past NEEDS_INPUT

**marketing_campaign_analytics**
Funnel rollup powered by the auto-injected tracker on the generated landing page. Events: `page_view`, `engage` (scroll>50% or time>15s), `cta_click` (any outbound link click), `conversion`. Total + per-variant counts plus CTR + conversion rate + revenue.
- Endpoint: `GET /api/agent/marketing/campaigns/{id}/analytics`
- Scope: `marketing:read` | Cost: 1¢
- Output: `{ totals: { page_views, engage, cta_clicks, conversions, revenueCents, ctr, conversionRate }, byVariant: [{ variantId, utmContent, headline, page_views, cta_clicks, conversions, ctr, conversionRate, revenueCents }] }`
- Attribution: visitors landing from a UTM-tagged link have their UTMs stored in sessionStorage; subsequent events are attributed to the variant that brought them in

### Partner mode (multi-tenant provisioning)

A Stripe-Connect-style surface exists for curated integrators who provision a separate plgd tenant per end-user, with partner-pays-all billing and a single webhook URL that fans events across all sub-tenants. It's gated and not part of the public agent API — if you're building a product that needs to provision tenants on plgd's behalf, email hi@plgd.ai for the partner reference doc and a `partner_xxx` credential. Otherwise this section isn't relevant to you.

### Agent Feed — pull-based event stream

Pull-side counterpart to webhooks. Stateless agents catch up via `GET /api/agent/feed?since=<cursor>` without hosting a webhook URL. Every event our system dispatches (`article:published`, `contact:created`, `campaign:sent`, `email:opened`, `email:clicked`, `signup:milestone`, etc.) writes to the feed regardless of whether the tenant has webhook subscriptions.
- Endpoint: `GET /api/agent/feed`
- Scope: `feed:read` | Cost: 1¢
- Query: `since=<cursor>` (opaque, from prior response's meta.nextCursor), `type=<event-type>` (repeatable), `source=<source>` (repeatable; "webhook" today, "email"/"rss"/"job"/"a2a" reserved), `limit=` (1-200, default 50).
- Response: `{ ok, data: [{ id, type, source, occurredAt, payload, externalId? }], meta: { count, hasMore, nextCursor } }`. Reverse-chronological. Tie-break on id when occurredAt collides.
- Real-time polling: track most-recent id you've seen, re-query without cursor each tick, stop on watermark.
- Why exists vs webhooks: agents that wake briefly (chat sessions, brief cron loops) can't host a webhook URL; this gives them a stateless catch-up path.

### Daily send caps (safety guard)

Every tenant has two ceilings enforced inside `sendCampaignNow` before audience build / credit deduction. Either trips → HTTP 429 `RATE_LIMITED` with a message naming the cap. The campaign rolls back to `status: "draft"` so callers can retry after 00:00 UTC or after raising the cap.
- `dailyCampaignSendsCap` — distinct campaign dispatches per UTC day. Default 5, range 1-1000.
- `dailyRecipientsCap`    — sum of totalSent across today's sends. Default 10000, range 1-1,000,000.
Raise via `PATCH /api/agent/site { dailyCampaignSendsCap, dailyRecipientsCap }` — both fields **require trust tier 2+**. Tier 0/1 tenants get TRUST_TIER_REQUIRED and have to go through support. Counters reset at 00:00 UTC.

### Brand identity (single-call push)

`PUT /api/agent/brand` accepts a structured brand payload, stores it on `Tenant.brandProfile` (canonical), and fans out to: `Tenant.tagline`, `Tenant.aiVoiceTone` (composed from voice+tone), `Tenant.aiAudience`, `Tenant.emailFromName`/`emailFromAddress`/`emailReplyTo` (when `sender` provided), and the default `EmailLayout` (when `emailLayoutHtml` provided — must contain `{{content}}`). Cost: 5¢. Does not regenerate the design system.
- Read: `GET /api/agent/brand` → `{ brandProfile, derived: { tagline, aiVoiceTone, aiAudience, emailFromName, emailFromAddress, emailReplyTo } }`. Scope: `site:read`.
- Write: `PUT /api/agent/brand`. Scope: `site:write`. Body: `{ name?, tagline?, voice?, tone?, audience?, founderName?, founderTitle?, sender?: { fromName?, fromAddress?, replyTo? }, emailLayoutHtml?, emailLayoutName?, ...any additional keys }`. Additional keys are stored on brandProfile for `{{brand.*}}` resolution.

### {{brand.*}} layout tokens

`renderWithLayout` substitutes `{{brand.<dot.path>}}` from a passed-in brand object. `renderContentWithLayout` defaults the brand to `Tenant.brandProfile`. Dot paths supported (`{{brand.sender.fromName}}`). Values HTML-escaped; unknown / non-scalar paths resolve to empty strings. Tokens can appear in wrapperHtml, headerHtml, footerHtml, styles. No caller change required — every send/preview now uses the tenant's brandProfile automatically.

### Webhook events — signup milestones

`signup:milestone` fires exactly once per (tenant, milestone) when the tenant's contact count crosses 1, 10, 100, 1000, or 10000. Server-side derivation via the TenantMilestone table; the unique constraint @@unique(tenantId, kind, milestone) makes concurrent contact creates idempotent — only one fire per crossing.
- Payload `data: { milestone: 10, kind: "signup", reachedAt: "<ISO>" }`.
- Carried under the standard webhook v1 envelope (`event`, `timestamp`, `meta.schema_version`, `data`).

### Bulk contact operations

Avoids 500 individual API calls when a lead-scoring or lifecycle agent needs to update a slice of contacts. Both endpoints accept `contactIds` OR `emails` (exactly one), tenant-scoped resolution, cost 5¢ flat per call regardless of N.
- `POST /api/agent/contacts/bulk-tag` body `{ contactIds? | emails?, tags, mode? }` (mode: "add" default | "remove"). Max 1000 targets, 50 tags per call. Idempotent: re-adding the same (contact, tag) is a no-op against the @@unique(tenantId, contactId, tag) index. Returns `{ matched, tagsAdded, tagsRemoved, mode }`.
- `POST /api/agent/contacts/bulk-update-properties` body `{ contactIds? | emails?, properties, mode? }` (mode: "merge" default | "replace"). Merge mode = shallow top-level merge onto Contact.metadata. Max 1000 targets, 50 keys per call. Returns `{ matched, updated, mode }`.
- Scope: `contacts:write` (both).

### Webhook events — email engagement

Added in Round 4. Both fire when Resend reports the corresponding event for a message we sent.
- `email:opened` payload `data: { email, contactId, externalId, resendMessageId, campaignId, campaignExternalId, openedAt }`. Also increments Contact.totalEmailsOpened + sets lastEmailOpenedAt.
- `email:clicked` payload `data: { email, contactId, externalId, resendMessageId, campaignId, campaignExternalId, url, clickedAt }`. Also increments Contact.totalEmailsClicked.
- externalId is the Contact's; campaignExternalId is the parent Campaign's (null for transactional sends with no campaign).

### Webhook signature verification

Two HMAC-SHA256 headers ship today on every outbound webhook delivery:
- `X-Plgd-Signature: sha256=<hex>` — canonical (Stripe convention). Verify against your subscription's `secret`.
- `X-Webhook-Signature: <hex>` — legacy, kept for ≥1 release. Will be deprecated with notice in SKILL.md.
Verification (Node): `crypto.createHmac("sha256", secret).update(rawBody).digest("hex")` — compare to the part after `sha256=` in the header.

### Preview URLs (signed tokens, iframe-embeddable)

Mint a short-lived HMAC-signed URL that renders an article, landing page, or email template as iframe-ready HTML — no API key needed in the iframe markup. Cross-origin embedding gated by the tenant's `previewFrameAncestors` (Content-Security-Policy: frame-ancestors).
- Mint:   `POST /api/agent/preview` body `{ kind: "article" | "landing-page" | "email-template", id, ttlSeconds? }` (default TTL 24h, max 7d). Returns `{ url, token, expiresAt }`.
- Render: `GET /api/preview/{kind}/{id}?token=...` (public, token-authed). Returns full HTML doc. Always sets `X-Robots-Tag: noindex, nofollow` + `Cache-Control: no-store`.
- Configure embedding: `PATCH /api/agent/site { previewFrameAncestors: ["https://app.example.com", "https://*.example.com"] }` — full https origins or wildcards, max 20 entries.
- Email-template previews substitute sample variables (`first_name` → "Alex", `app_name` → tenant name, unknown vars → `[var-name]`), wrap in the tenant's default email layout, inline CSS via juice — matches what Resend will actually deliver.
- Token kind/id mismatch (e.g. article token used against /preview/landing-page/…) → 403.
- Cost: 2¢ on mint. Public GET is free.

### Campaign drafts (review-canvas pattern)

`POST /api/agent/campaigns` defaults to `status: "draft"` so a human can review + edit before send. Pair with PATCH and the canonical `/send` endpoint:
- `POST /api/agent/campaigns` — creates draft. `externalId` accepted.
- `GET /api/agent/campaigns/{id}` — read full state (subject, body, audience, scheduledAt, externalId, status).
- `PATCH /api/agent/campaigns/{id}` — edit name / description / emailSubject / emailBody / emailPreheader / audienceType / audienceFilters / scheduledAt / externalId. Returns 409 CONFLICT once status has moved past draft.
- `POST /api/agent/campaigns/{id}/send` — canonical dispatch. `/send-now` stays as an alias for ≥1 release.
- Cost: 2¢ standard write + 1¢ per recipient on send.

### external_id round-trip

Top-level resources accept `externalId` (≤200 chars) on create. Stored, returned on GET, echoed under `data.externalId` in webhook payloads. Removes the need for a translation table on the caller side.
- Article: `POST /api/agent/articles { externalId }` → fires `article:published` with `data.externalId`
- Contact: `POST /api/agent/contacts { externalId }` → fires `contact:created` with `data.externalId`
- Campaign: `POST /api/agent/campaigns { externalId }` → fires `campaign:sent` with `data.externalId` on dispatch
- MarketingCampaign: `POST /api/agent/marketing/campaigns { externalId }` → echoed on GET

### Webhook payload envelope v1

Every webhook delivery wraps the event in:
```
{
  "event":     "campaign:sent",
  "timestamp": "2026-05-18T...",
  "meta":      { "schema_version": 1 },
  "data":      { ... event-specific payload, includes externalId on resource events ... }
}
```
Branch on `meta.schema_version` for handler evolution. Non-breaking additions (new optional fields in `data`) DO NOT bump schema_version; breaking shape changes will. Currently emitted events: `article:published`, `article:updated`, `article:deleted`, `contact:created`, `contact:updated`, `form:submitted`, `campaign:sent`, `seo:alert`. Coming next: `email:opened`, `email:clicked`, `signup:milestone`.

### Reliability primitives

**Idempotency-Key**
Every mutating endpoint (POST/PATCH/PUT/DELETE) accepts an `Idempotency-Key` header. Replays the original response if the same key + tenant arrives within 5 minutes. Replay responses carry `X-Idempotent-Replay: true` and `X-Idempotent-Original-At: <ISO>` so callers can tell. Generate one v4 UUID per logical agent intent and reuse across retries.

**Response headers on every agent endpoint**
- `X-RateLimit-Remaining` — calls left in the current 1-minute window
- `X-RateLimit-Reset` — Unix epoch seconds when the window resets; pace off this
- `X-Credits-Remaining` — tenant credit balance in cents after this call
Default rate limit: 60 req/min (tier 0/1), 120 req/min (internal). 429 with `RATE_LIMITED` when exhausted.

**Per-request test mode**
Pass `X-Plgd-Test: true` on any agent request to run the full pipeline without billing for fal.ai images, Migadu provisioning, or live email sends. Only ELEVATES test mode (a production key with the header acts as test for that request; test-mode keys never revert to live). Response includes `X-Plgd-Test-Mode: request` when applied. For founder-review use cases, prefer the campaign draft state instead.

**Audience filter syntax** (campaign + automation `audienceFilters`)
```
{
  // Pick one primary selector:
  all?: boolean,                   // every ACTIVE contact
  contactIds?: string[],           // explicit selection
  tags?: string[],                 // contacts having any of these tags
  // Optional additive filters:
  minEngagementScore?: number,     // 0-100, score >=
  activeInLastDays?: number,       // received email within last N days
}
```
Always excluded: suppressed / unsubscribed / bounced / complained. Use `POST /api/agent/audience/preview` to confirm resolved contact count before committing to a send.

**Custom contact properties**
`Contact.metadata` is a free-form JSON object. Write per-contact data your agent needs (lifecycle_stage, lead_score, last_seen_url). PLGD stays a flat store; your side keeps the brain.
- Endpoint: `POST /api/agent/contacts` or `PATCH /api/agent/contacts/{id}` — `{ email, metadata: { ... } }`
- Scope: `contacts:write` | Cost: 2¢

**MCP tool stability tiers**
Every MCP tool description is prefixed with its stability: `[stable]`, `[beta]`, or `[experimental]`.
- stable: shape locked. May add optional fields, never renames or removes. Production-safe.
- beta: shape stable enough to integrate. Renames only with a one-release deprecation window.
- experimental: expect changes. Don't pin production loops without a fallback.
Current state: most tools stable. Tier 1 set (snippets, email layouts, mailboxes, suppressions, translations, content-audit, suggest-links, email-domains, email-templates CRUD, marketing campaign suite, x402 pay) tagged beta. Nothing currently experimental.

**track event (public, no auth)**
Public funnel event ingest. Called automatically by the tracker snippet that's injected into every marketing-generated landing page. Cookieless (sessionId in localStorage), Do-Not-Track honored, rate-limited 60 req/min per IP, IPs hashed with a rotating daily salt.
- Endpoint: `POST /api/site/track`
- Auth: none | Cost: free
- Input: `{ tenantId, type: "page_view"|"engage"|"cta_click"|"conversion", sessionId, utm?, marketingCampaignId?, variantId?, metadata?, conversionValueCents? }`
- Resolves marketingCampaignId/variantId from UTMs automatically when not provided explicitly

### Images (logos, hero images, OG cards)

Host binary images on plgd so you can reference them from PATCH /api/agent/site (logo, favicon, OG image), articles, pages, or anywhere else expecting a URL. Idempotent on SHA256 — re-uploading the same bytes returns the existing row.

**upload_image**
- Endpoint: `POST /api/agent/images`
- Scope: `images:write` | Cost: 5¢
- Accepts multipart (`file`, `alt`, `tags`, `externalId`) OR JSON `{ data: "<base64>", mimeType, alt?, tags?, externalId? }`. The base64 form accepts `data:image/png;base64,...` prefixes too.
- Mime: `image/jpeg`, `image/png`, `image/webp`, `image/gif`, `image/svg+xml`. Max 10MB.
- Output: `{ id, url, checksum, width, height, sizeBytes, mimeType, altText, tags, deduplicated }`. `deduplicated: true` when same bytes were uploaded before — status code distinguishes (201 fresh, 200 dedupe).

**list_images / get_image / delete_image**
- `GET /api/agent/images?tag=brand&page=1&limit=50` — list (tenant-scoped). `images:read`. 1¢.
- `GET /api/agent/images/{id}` — single. `images:read`. 1¢.
- `DELETE /api/agent/images/{id}` — remove row. `images:write`. 2¢.

PATCH endpoints with URL fields (`logoUrl`, `faviconUrl`, `heroImageUrl`, `homeOgImage`) reject `data:` URIs with 400 — upload first, then pass the URL.

**logoLayout** — header brand rendering control.
- `icon-with-text` (default) — image + name + tagline. Image falls back to a tenant-color SVG mark when logoUrl is null.
- `wordmark-only` — image only; name and tagline are suppressed in the header (still set in metadata/OG for SEO). Use when your logoUrl is a wide wordmark that already spells the brand. Falls back to `text-only` when no image is set.
- `text-only` — name + tagline; no image even if logoUrl is set.
- `icon-only` — image (or fallback SVG); name + tagline suppressed.
Set via `PATCH /api/agent/site { logoLayout: "wordmark-only" }`. Default preserves prior behavior — existing tenants see no change.

### Analytics (GA4, GTM, Meta Pixel, PostHog, LinkedIn)

Typed ID fields on the Tenant. Set via `PATCH /api/agent/site`; rendered as vendor-recommended browser snippets on every page automatically. Replaces the brittle "PATCH customJs with raw gtag/fbq" pattern.

- `googleAnalyticsId` — GA4 measurement ID, format `G-XXXXXXXXXX`. Renders gtag.js + config.
- `googleTagManagerId` — GTM container ID, format `GTM-XXXXXXX`. Renders the GTM bootstrap. Preferred over the legacy `googleTagId` field.
- `metaPixelId` — 15–16 digit numeric. Renders fbq + PageView + <noscript> fallback.
- `posthogProjectKey` — `phc_*`. Renders PostHog with host us.i.posthog.com.
- `linkedInPartnerId` — numeric. Renders LinkedIn Insight Tag + <noscript> fallback.

Each field is format-validated at write time — malformed IDs return 400 instead of silently breaking the page. Clear by sending `null` or `""`. `customJs` is still available for bespoke snippets these don't cover.

**Server-side secret fields** (reserved for the upcoming Conversion API pipeline):
- `metaCapiAccessToken` — Meta CAPI access token.
- `googleMeasurementProtocolSecret` — GA4 Measurement Protocol secret.
Both are write-only via PATCH and never returned by GET /api/agent/site. Storage works today; the outbound event pipeline does not (filing freq-1779898420868-g7029n Ask 2).

### Google Analytics 4 — read traffic data from the tenant's GA4 property

Phase 1 connector — service account JSON auth + three read endpoints. The operator uploads a Google Cloud service account JSON, grants it Viewer access in GA4 admin, and plgd handles the GA4 Data API calls.

**connect_google_analytics**
- Endpoint: `POST /api/agent/integrations/google-analytics/connect`
- Scope: `analytics:write` | Cost: 2¢
- Input: `{ serviceAccountJson: <SA JSON object>, propertyId: "properties/123..." | "123..." }`
- Round-trips a one-day ping against GA4 to verify the SA has read access before persisting; returns 400 with a user-actionable error if the SA isn't granted.
- Output: `{ connected: true, propertyId, lastValidatedAt }` — SA JSON NEVER returned.

**get_google_analytics_status** + **disconnect_google_analytics**
- `GET /api/agent/integrations/google-analytics/status` — `analytics:read`, 1¢. Returns the connection-status shape without the SA JSON.
- `DELETE /api/agent/integrations/google-analytics` — `analytics:write`, 2¢. Idempotent.

**Range parameter** (shared by all read endpoints) — `today | yesterday | 7d | 30d | mtd | custom`. For custom: `?range=custom&from=YYYY-MM-DD&to=YYYY-MM-DD`. Every response echoes `meta.range = { key, label, start, end }`.

**get_ga4_sessions**
- Endpoint: `GET /api/agent/integrations/google-analytics/sessions?range=7d`
- Scope: `analytics:read` | Cost: 1¢
- Output: `{ data: { total, prior_total, delta_pct, timeseries: [{ date, sessions, users }] } }`
- Prior_total is the matching previous period; delta_pct rounded to 1 decimal, null when prior=0.

**get_ga4_by_channel**
- Endpoint: `GET /api/agent/integrations/google-analytics/by-channel?range=7d`
- Scope: `analytics:read` | Cost: 1¢
- Dimension: `sessionDefaultChannelGroup` (Paid Social / Direct / Organic Search / Email / Referral / etc.).
- Output: `{ data: [{ channel, sessions, users, engagement_rate, conversions }, ...] }` sorted by sessions desc.

**get_ga4_top_pages**
- Endpoint: `GET /api/agent/integrations/google-analytics/top-pages?range=7d&limit=25`
- Scope: `analytics:read` | Cost: 1¢
- `limit` default 25, cap 100. Sorted by sessions desc.
- Output: `{ data: [{ page_path, sessions, users, avg_engagement_time_sec, bounce_rate, conversions }, ...] }`
- `avg_engagement_time_sec` is `userEngagementDuration / sessions` rounded to seconds (GA4 reports total engagement seconds, this normalizes per-session).

**Setup**: Create SA in Google Cloud → IAM → Service Accounts → keys. In GA4 admin → Property Access Management → add the SA email as Viewer. propertyId is at GA4 Admin → Property Settings; accepts numeric or `properties/XXXX` form.

**Phase scope** — sessions/by-channel/top-pages only. Events, by-source-medium, Search Console, OAuth flow are gated on real usage signal (filing freq-1780356729167-wftufg phase 2+). File feature requests if you need them.

### Lifecycle sequences (drip emails)

Integrator owns *when* to enroll/unenroll a contact. plgd owns *how* the sequence delivers — ordered, time-offset, suppression-aware, deduplicated against retries. Backed by Campaign(type=automation) + AutomationStep under the hood; exposed as a cleaner "sequence" surface for integrators.

**create_sequence**
- Endpoint: `POST /api/agent/sequences`
- Scope: `sequences:write` | Cost: 2¢
- Input: `{ name, externalId?, steps: [{ key?, offsetHours?|offsetDays?, subject, body, preheader? }] }` (max 20 steps)
- Output: `{ id, name, status, steps: [...] }`
- `externalId` is unique per tenant — duplicate POST returns 409 with `existingId`.

**enroll_in_sequence** (the core)
- Endpoint: `POST /api/agent/sequences/{id}/enroll`
- Scope: `sequences:enroll` | Cost: 2¢
- Headers: `Idempotency-Key` (recommended)
- Input: `{ contactId | email, externalId?, variables?, startAt? }`
- Output: `{ id, currentStep: 1, status: "active", nextStepAt, ... }`
- Sequence-level `offsetMode` (default `cumulative` for back-compat) controls step timing semantics: `absolute` measures each step's offset from `enrollment.enrolledAt` (so `[0, 1, 3, 7]` fires at enrollment days `[0, 1, 3, 7]`); `cumulative` measures from the previous step's processing time (so the same offsets fire at days `[0, 1, 4, 11]`). Snapshotted per-enrollment at enroll time so PATCHing the mode is safe — only NEW enrollments pick up the change.
- Two layers of idempotency: re-POST with same `externalId` returns the existing enrollment; re-POST for a contact already active in the sequence returns the existing enrollment. Both 200, not 201.
- Suppressed contacts (UNSUBSCRIBED/BOUNCED/COMPLAINED) return 200 with `skipped: true` — safe no-op, not an error.
- `testRecipient` (optional email): when set, every step send for this enrollment is diverted to that address. Real enrollment row, real cadence, real webhooks, real supersede/suppression — full pipeline behavior. Use for QAing cadence + webhooks + supersede end-to-end before going live. Bills per-step at 1¢. `sequence:*` webhook payloads include `testRecipient` so handlers can route differently.

**unenroll_from_sequence**
- Endpoint: `POST /api/agent/sequences/{id}/unenroll`
- Scope: `sequences:enroll` | Cost: 2¢
- Input: `{ enrollmentId | contactId | email, reason? }`
- Idempotent. Cancels in-flight steps immediately. Use for supersede ("quiz_journey supersedes signup_welcome") and stop-on-conversion.

**send_sequence_test**
- Endpoint: `POST /api/agent/sequences/{id}/send-test`
- Scope: `sequences:write` | Cost: 1¢ per step (real Resend sends)
- Input: `{ email, variables? }` — sends every step IMMEDIATELY to the email address (collapses the cadence). Use to preview the full drip before going live.
- Same render path as production: integrator `{{var.*}}` merged first, then system vars (`{{first_name}}`, `{{email}}`, etc.), then layout wrap. The synthetic system vars default to "Test Recipient" / the test email if not supplied.
- Output: `{ sequenceId, email, sent: N, failed: N, steps: [{ stepNumber, stepKey, resendId, status }, ...] }`
- Skips Message persistence (recipient is an arbitrary email, not a tenant Contact). Resend dashboard is the audit trail.
- Requires `emailFromName` + `emailFromAddress` configured on tenant. Capped at 20 steps per call.

**list_sequences / get_sequence / patch_sequence / delete_sequence**
- `GET /api/agent/sequences` and `/{id}` — `sequences:read`. 1¢.
- `PATCH /api/agent/sequences/{id}` — `sequences:write`. 2¢. Replacing `steps[]` propagates new copy to in-flight enrollments on their next scheduled fire.
- `DELETE /api/agent/sequences/{id}` — `sequences:write`. 2¢. Soft-delete: stops the sequence + cancels in-flight enrollments. Message rows remain queryable.

**Merge variables.** Step copy may reference `{{var.<name>}}` (e.g. `{{var.first_name}}`, `{{var.archetype}}`). Values come from `variables` on enroll, are HTML-escaped, and are FROZEN at enroll time — editing the sequence later doesn't retroactively change copy already in a sent message. The `{{var.*}}` namespace is separate from system tokens (see below).

**System tokens** — injected by the renderer at send time, no `var.` prefix:
- Per-recipient: `{{first_name}}`, `{{last_name}}`, `{{email}}`, `{{unsubscribe_url}}`, `{{preferences_url}}`.
- Per-tenant: `{{app_name}}` (Tenant.name), `{{from_name}}` (Tenant.emailFromName or Tenant.name), `{{physical_address}}` (Tenant.address).
- Per-send: `{{preheader}}` (Campaign.emailPreheader — shown in inbox preview pane).
- Layout-only: `{{content}}` (required placeholder in EmailLayout.wrapperHtml — the step body substitutes here).

`{{brand.*}}` tokens (e.g. `{{brand.name}}`, `{{brand.tagline}}`, `{{brand.voice}}`) resolve from `Tenant.brandProfile` at layout-render time. Set via `PUT /api/agent/brand`.

`{{unsubscribe_url}}` and `{{preheader}}` are REQUIRED in marketing layouts. `POST /api/agent/email/layouts` returns 400 if either is missing from `wrapperHtml`. The default-layout scaffold (`POST /api/agent/email/layouts/seed-default`) ships both correctly.

**RFC 8058 List-Unsubscribe headers** (Gmail/Yahoo bulk-sender requirement since Feb 2024): plgd does NOT inject these today. The visible `{{unsubscribe_url}}` satisfies the click-to-unsubscribe requirement but not the one-click header. If your deliverability degrades, file a feature request for header injection.

**No tokens for**: view-in-browser URL, tracking pixel (Resend injects open tracking automatically — no token needed), tenant ID. File feature requests if needed.

**Webhooks (Phase 1).** Subscribe via POST /api/agent/webhooks with one or more of:
- `sequence:enrolled` — `{ enrollmentId, sequenceId, contactId, externalId }`
- `sequence:step_sent` — `{ enrollmentId, sequenceId, stepNumber, stepKey, contactId, messageId, externalId }` — fires after Resend confirms the step send.
- `sequence:unenrolled` — `{ enrollmentId, sequenceId, contactId, externalId, reason }`
- `sequence:unsubscribed` — `{ enrollmentId, sequenceId, contactId, externalId, scope: "all" }` — fires when an unsubscribe cascades and cancels active enrollments.

Phase 2 will add `sequence:step_opened`, `sequence:step_clicked`, `sequence:completed`, mid-flight `PATCH` of enrollment variables. Phase 3 (conditional branching, A/B step variants, per-step content callbacks) is deliberately out of scope — that's journey logic, which lives on the integrator side.

### Feedback to plgd (feature requests + bugs)

When you hit something plgd doesn't expose yet — a missing endpoint, a missing scope, a schema field you wish existed, or a bug that blocked you — file it instead of escalating out-of-band. The operator gets emailed for ENDPOINT/SCOPE/SCHEMA/BUG categories; OTHER is wishlist-only.

**file_feature_request**
- Endpoint: `POST /api/agent/feature-requests`
- Scope: `feature-requests:write` | Cost: **free**
- Input: `{ title, body, category?: "ENDPOINT"|"SCOPE"|"SCHEMA"|"BUG"|"OTHER", urgency?: "LOW"|"MEDIUM"|"HIGH"|"BLOCKING", externalId? }`
- Output: `{ id, category, urgency, status: "OPEN", title, body, externalId, createdAt }`
- `externalId` is unique per tenant — re-POST with the same id returns 409 instead of duplicating.
- Status lifecycle: `OPEN → TRIAGED → IN_PROGRESS → SHIPPED` (or `WONTFIX` / `DUPLICATE`).

**list_feature_requests**
- Endpoint: `GET /api/agent/feature-requests`
- Scope: `feature-requests:read` | Cost: **free**
- Query: `status?`, `category?`, `page?`, `limit?`
- Returns only this tenant's filings.

**get_feature_request**
- Endpoint: `GET /api/agent/feature-requests/{id}`
- Scope: `feature-requests:read` | Cost: 1¢
- Use to poll: when `status` becomes `SHIPPED`/`WONTFIX`/`DUPLICATE`, the `resolution` field is populated with the operator's note.

### Infrastructure

**create_async_job**
Queue AI work and poll for results (non-blocking alternative to sync AI calls).
- Endpoint: `POST /api/agent/jobs`
- Scope: `jobs:write` | Cost: 2¢ (AI cost deducted on completion)
- Input: `{ action: "story:create"|"story:outline"|"story:draft"|"story:images"|"seo:generate"|"ideas:generate"|"creative:generate"|"creative:refine", resourceId?, payload? }`
- Output: `{ id, action, status: "PENDING" }`
- Poll: `GET /api/agent/jobs/{id}` until `status` is `COMPLETED` or `FAILED`
- Triggers: `job:completed` or `job:failed` webhook

**check_usage**
See remaining credits and monthly usage.
- Endpoint: `GET /api/agent/whoami`
- Auth: Any valid key | Cost: 1¢
- Output: `{ key: { scopes }, tenant: { name, canonicalHost }, credits: { remainingCents }, usage: { requests, tokens } }`

**get_analytics**
View article performance and trends.
- Endpoint: `GET /api/agent/articles/{id}/analytics`
- Scope: `analytics:read` | Cost: 1¢
- Use `id=top` for leaderboard: `?limit=20`
- Output: `{ totalViews, last7Days: { views, trend }, last30Days: { views }, daily: [...] }`

## Workflows

Step-by-step execution paths. Each step is one API call. Costs are cumulative.

### Launch a News Site
**Total: ~57¢ | 8 API calls | Result: live news site with 3 articles, SEO optimized**

```
1. create_site       POST https://plgd.ai/api/signup { name: "City Herald" }                    → api_key       [free]
2. set_theme         PATCH /api/agent/site { layoutTemplate: "minimal" }                    → live           [2¢]
3. add_navigation    POST  /api/agent/navigation { label: "News", path: "/blog" }          → nav item       [2¢]
4. add_navigation    POST  /api/agent/navigation { label: "About", path: "/about" }        → nav item       [2¢]
5. batch_publish     POST  /api/agent/articles/batch { articles: [{...},{...},{...}] }      → 3 articles     [15¢]
6. configure_brand   PATCH /api/agent/site { customCss: "..." }                             → styled         [2¢]
7. audit_seo         GET   /api/agent/seo/audit                                             → scores         [1¢]
8. generate_seo      POST  /api/agent/seo/generate { articleId: "..." }                     → metadata      [10¢]
```

### Run a Newsletter
**Total: ~12¢ | 5 API calls | Result: subscription form, contacts, campaign, webhook notifications**

```
1. create_form       POST /api/agent/forms { title: "Subscribe", slug: "subscribe",
                       fields: [{ name: "email", type: "email", label: "Email", required: true }] }  [2¢]
2. add_contact       POST /api/agent/contacts { email: "reader@example.com", tags: ["launch"] }      [2¢]
3. add_contact       POST /api/agent/contacts { email: "fan@example.com", tags: ["launch"] }         [2¢]
4. send_campaign     POST /api/agent/campaigns { name: "Issue #1",
                       emailSubject: "Welcome!", emailBody: "<h1>Hello</h1>..." }                     [2¢]
5. subscribe_webhook POST /api/agent/webhooks { url: "https://...",
                       events: ["contact:created", "form:submitted"] }                                [2¢]
```

### Build a Landing Page with Lead Capture
**Total: ~38¢ | 6 API calls | Result: dark-themed landing page with design system, waitlist form, and webhook**

```
1. generate_design   POST  /api/agent/design-system/generate { brief: "Modern SaaS,
                       primary indigo #6366f1, dark mode, clean sans-serif" }               [25¢]
2. create_page       POST  /api/agent/pages { path: "/launch", title: "Launch",
                       content: "<section>...</section>", status: "PUBLISHED" }              [2¢]
3. create_form       POST  /api/agent/forms { title: "Waitlist", slug: "waitlist",
                       fields: [{ name: "email", type: "email" }, { name: "company", type: "text" }] } [2¢]
4. manage_redirects  POST  /api/agent/redirects { fromPath: "/", toPath: "/launch" }        [2¢]
5. render_page       GET   /api/agent/pages/{id}/render                                     [1¢]
6. subscribe_webhook POST  /api/agent/webhooks { url: "https://...",
                       events: ["form:submitted"] }                                          [2¢]
```

### AI Content Pipeline
**Total: ~47¢ | 6 API calls | Result: AI-researched, AI-written, SEO-optimized, published article**

```
1. generate_ideas    POST /api/agent/ideas { prompt: "local tech startups" }                [10¢]
2. generate_article  POST /api/agent/articles/new/story { action: "create",
                       title: "..." }                                                       [25¢]
3. generate_seo      POST /api/agent/seo/generate { articleId: "..." }                     [10¢]
4. publish           PATCH /api/agent/articles/{id} { status: "PUBLISHED" }                  [2¢]
5. audit_seo         GET  /api/agent/seo/audit?slug=article-slug                             [1¢]
6. get_analytics     GET  /api/agent/articles/{id}/analytics                                 [1¢]
```

### Generate a Creative Landing Page
**Total: ~75¢ (or ~95¢ with 4 AI images) | 1-2 API calls | Result: high-design interactive page with scroll animations, gradient text, glassmorphism**

```
1. generate_creative POST /api/agent/creatives/generate { prompt: "Launch page for
                       Aether, an AI design tool. Futuristic, dark, electric.",
                       headline: "Design at the speed of thought.",
                       includeImages: true }                                                 [95¢]
2. refine_creative   POST /api/agent/creatives/{id}/refine { feedback: "Add a
                       metrics section showing 10K+ users, 99.9% uptime" }                   [25¢]
```
Note: includeImages generates AI images via fal.ai (5¢ per image, billed for actual count). Test-mode keys bypass.

### Build a Branded Creative Site
**Total: ~$1.35 | 4 API calls | Result: design system + reusable components + full creative page**

```
1. generate_design_system  POST /api/agent/design-system/generate  { brief }                     [30¢]
2. generate_component      POST /api/agent/components/generate     { prompt: "Hero section" }     [15¢]
3. generate_component      POST /api/agent/components/generate     { prompt: "Feature card" }     [15¢]
4. generate_creative       POST /api/agent/creatives/generate      { prompt, sections }           [75¢]
```

### Async Workflow (Non-Blocking)
**For long-running AI operations — queue work, get notified when done.**

```
1. create_async_job  POST /api/agent/jobs { action: "story:create",
                       payload: { title: "..." } }                                           [2¢]
2. subscribe_webhook POST /api/agent/webhooks { url: "https://...",
                       events: ["job:completed", "job:failed"] }                              [2¢]
3. (wait for webhook or poll)
4. check_job         GET  /api/agent/jobs/{id}                                               [1¢]
```

## Pricing

$5.00 free credits on signup (500¢).

### Cost per Operation

| Operation | Cost |
|-----------|------|
| Read (any GET) | 1¢ |
| Write (POST/PATCH/DELETE) | 2¢ |
| Batch create (per article) | 5¢ |
| AI: Idea generation | 10¢ |
| AI: SEO generation | 10¢ |
| AI: Image suggestion | 10¢ |
| AI: Component generation | 15¢ |
| AI: Creative page refinement | 25¢ |
| AI: Design system generation | 30¢ |
| AI: Email template generation | 30¢ |
| AI: Site chrome generation | 25¢ |
| AI: Story pipeline | 40¢ |
| AI: Creative page generation | 75¢ |
| Per email sent (Resend) | 1¢ |
| Per AI image (fal.ai) | 5¢ |

### Cost per Outcome

| Outcome | Cost | API Calls |
|---------|------|-----------|
| Launch a basic site (theme + nav) | ~10¢ | 4 |
| Publish 10 articles (batch) | 50¢ | 1 |
| AI-written article with SEO | ~52¢ | 6 |
| Full site with content + SEO | ~$3-5 | 20-30 |
| Newsletter setup (form + welcome email template + contacts) | ~38¢ | 5 |
| Landing page with lead capture | ~80¢ | 5 |
| AI creative landing page | ~75¢ | 1 |
| AI creative with 4 generated images | ~95¢ | 1 |

### Checking Balance

- `GET /api/agent/whoami` → `credits.remainingCents`
- Response header: `X-Credits-Remaining` (every response)
- When credits run out: HTTP 402 with `INSUFFICIENT_CREDITS`

### Budget-aware Planning

- `GET /api/agent/usage/pricing` — public manifest of all costs (standard ops, per-action, AI operations).
- `POST /api/agent/usage/estimate` — declare a planned sequence of calls, get total cost + balance check before running. Body: `{ calls: [{ method, path, articleCount?, imageCount?, emailRecipients? }] }`. Free.

### Verifying a Build

- After publishing a creative or article, confirm with `GET /api/agent/pages?path=/blog/{slug}` — returns `{ data: [page] }` if it landed; `meta.total: 0` if it didn't.
- Article slug: `GET /api/agent/articles?slug={slug}` returns the same shape.

## Authentication

Two methods (both work on all endpoints):
- `X-Agent-Key: agk_...` — API key from signup
- `Authorization: Bearer oat_...` — OAuth 2.0 access token

Rate limit: 60 requests/minute per key (120 for tier 3).

API keys can optionally be restricted to an IP allowlist. Requests from non-allowed IPs are rejected with `IP_NOT_ALLOWED` (403).

Signup: `POST https://plgd.ai/api/signup` — no auth required, returns API key + OAuth credentials.

**CLI device flow** (alternative to copy-pasting a key): tools like Claude Code, Codex, or the standalone `plgd` CLI can authenticate via OAuth-2.0-style device flow. The CLI calls `POST /api/cli/auth/start`, gets back `{ deviceCode, userCode, verificationUrl, interval }`, prints the URL + 8-char code to the user, then polls `POST /api/cli/auth/poll` until the user approves in their browser. Approval mints an `agk_…` key bound to the user's current tenant; raw key is delivered one-shot to the CLI and cleared from the row.
- Standalone CLI: `curl -fsSL https://plgd.ai/cli/plgd.mjs -o ~/.local/bin/plgd && chmod +x ~/.local/bin/plgd && plgd login`
- Codes expire in 10 minutes. Poll interval is 2s; faster polls get `slow_down` (429).
- Approval page lives at `https://plgd.ai/cli/auth/<userCode>` and requires the user to be logged into the plgd admin.

## Trust Tiers

Every tenant is assigned a trust tier (0–3) that gates access to sensitive features like code injection, webhooks, and domain management. Tiers are set by admins — agents cannot change their own tier.

| Tier | Name | Access |
|------|------|--------|
| 0 | Trial | New signups. Content CRUD, design system, AI generation, basic branding. **Cannot use:** `customJs`, `customCss`, `headerHtml`, `footerHtml`, webhooks, domain management. |
| 1 | Verified | Admin-upgraded. Adds: `customCss`, webhook creation, domain management. |
| 2 | Trusted | Reviewed users. Adds: `headerHtml`, `footerHtml`, `customJs` (full code injection). |
| 3 | Internal | No restrictions. Higher rate limits (120 req/min vs 60). |

### Checking Your Tier

`GET /api/agent/whoami` returns `tenant.trustTier` (integer 0–3).

### Tier-Gated Fields

- `PATCH /api/agent/site` — `customCss`: tier 1+, `headerHtml`/`footerHtml`/`customJs`: tier 2+
- `POST /api/agent/webhooks` — tier 1+
- `POST /api/agent/domains`, `DELETE /api/agent/domains` — tier 1+
- `PATCH /api/agent/pages/{id}` — `customJs` field: tier 2+

If you attempt a gated operation, you receive HTTP 403 with error code `TRUST_TIER_REQUIRED`. The `details` object includes `currentTier` and `requiredTier`.

### IP Allowlists

API keys can be restricted to specific IP addresses. If a request comes from an IP not on the key's allowlist, it is rejected with `IP_NOT_ALLOWED` (403). Configure allowlists via the admin key management UI.

## Scopes

Keys are granted scopes at creation. If a key is missing a scope, the error includes `details.missing` and `details.upgrade_url`.

- `articles:read` — Read articles
- `articles:write` — Write articles
- `images:read` — Read images
- `images:write` — Write images
- `seo:read` — Read seo
- `seo:write` — Write seo
- `ideas:read` — Read ideas
- `ideas:write` — Write ideas
- `site:read` — Read site
- `site:write` — Write site
- `pages:read` — Read pages
- `pages:write` — Write pages
- `navigation:read` — Read navigation
- `navigation:write` — Write navigation
- `journalist:write` — Write journalist
- `usage:read` — Read usage
- `redirects:read` — Read redirects
- `redirects:write` — Write redirects
- `contacts:read` — Read contacts
- `contacts:write` — Write contacts
- `campaigns:read` — Read campaigns
- `campaigns:write` — Write campaigns
- `campaigns:send` — Write campaigns
- `analytics:read` — Read analytics
- `analytics:write` — Write analytics
- `domains:write` — Write domains
- `webhooks:read` — Read webhooks
- `webhooks:write` — Write webhooks
- `forms:read` — Read forms
- `forms:write` — Write forms
- `jobs:read` — Read jobs
- `jobs:write` — Write jobs
- `creatives:read` — Read creatives
- `creatives:write` — Write creatives
- `design-system:read` — Read design-system
- `design-system:write` — Write design-system
- `email-templates:read` — Read email-templates
- `email-templates:write` — Write email-templates
- `email-layouts:read` — Read email-layouts
- `email-layouts:write` — Write email-layouts
- `email-mailboxes:read` — Read email-mailboxes
- `email-mailboxes:write` — Write email-mailboxes
- `email-suppressions:read` — Read email-suppressions
- `email-domains:read` — Read email-domains
- `email-domains:write` — Write email-domains
- `snippets:read` — Read snippets
- `snippets:write` — Write snippets
- `translations:write` — Write translations
- `marketing:read` — Read marketing
- `marketing:write` — Write marketing
- `feed:read` — Read feed
- `feature-requests:read` — Read feature-requests
- `feature-requests:write` — Write feature-requests
- `sequences:read` — Read sequences
- `sequences:write` — Write sequences
- `sequences:enroll` — Write sequences

## Response Format

All responses are JSON.

Success:
```json
{ "ok": true, "data": { ... }, "meta": { "page": 1, "total": 42 } }
```

Error:
```json
{ "ok": false, "error": { "code": "INSUFFICIENT_SCOPES", "message": "...", "details": { "required": [...], "granted": [...], "missing": [...], "upgrade_url": "..." } } }
```

Error codes: `MISSING_KEY`, `INVALID_KEY`, `KEY_EXPIRED`, `INSUFFICIENT_SCOPES`, `TRUST_TIER_REQUIRED`, `IP_NOT_ALLOWED`, `RATE_LIMITED`, `REQUEST_BUDGET_EXCEEDED`, `TOKEN_BUDGET_EXCEEDED`, `INSUFFICIENT_CREDITS`, `VALIDATION_ERROR`, `NOT_FOUND`, `DUPLICATE`, `CONFLICT`, `INTERNAL_ERROR`

Conflict prevention: Pass `ifUpdatedAt` on PATCH requests. Returns 409 `CONFLICT` if the resource changed since that timestamp.

## Full API Reference

### Content

- **GET /api/agent/articles** [articles:read] — List articles. Query: ?page=1&limit=50&status=PUBLISHED&category=NEWS&q=search
- **POST /api/agent/articles** [articles:write] — Create article. Body: { title, slug, content?, excerpt?, author?, category?, status?, keywords?, heroImageUrl?, scheduledAt? }
- **POST /api/agent/articles/batch** [articles:write] — Batch create (max 20). Body: { articles: [...] }. 5¢ per article.
- **GET /api/agent/articles/{id}** [articles:read] — Get article by ID.
- **PATCH /api/agent/articles/{id}** [articles:write] — Update article. Supports ifUpdatedAt for conflict prevention.
- **DELETE /api/agent/articles/{id}** [articles:write] — Delete article. Triggers article:deleted webhook.
- **POST /api/agent/articles/{id}/story** [journalist:write] — AI story pipeline. Body: { action: "create"|"outline"|"draft"|"images"|"publish" }. 40¢.
- **GET /api/agent/ideas** [ideas:read] — List idea sessions. Query: ?limit=20&offset=0
- **POST /api/agent/ideas** [ideas:write] — Generate ideas. Body: { prompt, category?, provider?: "claude"|"perplexity", numberOfIdeas?: 1-15 }. 10¢.

### Pages & Structure

- **GET /api/agent/pages** [pages:read] — List pages. Query: ?status=PUBLISHED
- **POST /api/agent/pages** [pages:write] — Create page. Body: { path, title, content?, kind?, status?, editorMode? }
- **GET /api/agent/pages/{id}** [pages:read] — Get page by ID.
- **PATCH /api/agent/pages/{id}** [pages:write] — Update page. Supports ifUpdatedAt. customJs field requires trust tier 2+.
- **DELETE /api/agent/pages/{id}** [pages:write] — Delete page.
- **GET /api/agent/pages/{id}/render** [pages:read] — Render full HTML with theme CSS, header, footer. Returns text/html.
- **GET /api/agent/pages/{id}/revisions** [pages:read] — List revisions with version numbers.
- **POST /api/agent/pages/{id}/revisions?version=N** [pages:write] — Restore to version N.
- **GET /api/agent/navigation** [navigation:read] — List navigation items (ordered).
- **POST /api/agent/navigation** [navigation:write] — Create nav item. Body: { label, path, parentId?, order?, isVisible? }
- **PATCH /api/agent/navigation?id={id}** [navigation:write] — Update nav item.
- **DELETE /api/agent/navigation?id={id}** [navigation:write] — Delete nav item.
- **GET /api/agent/redirects** [redirects:read] — List redirects. Query: ?active=true
- **POST /api/agent/redirects** [redirects:write] — Create/upsert redirect. Body: { fromPath, toPath, statusCode?: 301|302|307|308 }
- **DELETE /api/agent/redirects?id={id}** [redirects:write] — Delete redirect.

### Creatives (AI Pages)

- **GET /api/agent/creatives** [creatives:read] — List creative pages. Query: ?status=PUBLISHED
- **POST /api/agent/creatives/generate** [creatives:write] — Generate creative page. Body: { prompt, style?, headline?, subheadline?, ctaText?, ctaUrl?, sections?, path?, status?, includeNav?, includeFooter?, includeImages?, advancedTypography? }. 75¢ + 5¢ per AI image.
- **GET /api/agent/creatives/{id}** [creatives:read] — Get creative with full HTML content and generation metadata.
- **POST /api/agent/creatives/{id}/refine** [creatives:write] — Refine creative. Body: { feedback }. 25¢.

### Design System

- **POST /api/agent/design-system/generate** [design-system:write] — AI-generate design system from brand brief. Body: { brief }. 30¢.
- **POST /api/agent/site/generate-chrome** [site:write] — AI-generate shared <nav> + <footer> for the tenant, styled to the design system. Body: { navItems?, ctaText?, ctaUrl? }. Persists to tenant.chromeHeader/chromeFooter. 25¢.
- **GET /api/agent/usage/pricing** [public] — Live cost schedule (standard ops + per-action + AI operations). No auth required.
- **POST /api/agent/usage/estimate** [auth-only] — Estimate the cost of a planned sequence. Body: { calls: [{ method, path, articleCount?, imageCount?, emailRecipients? }] }. Returns { totalCents, breakdown, balance.sufficient }. Free.
- **GET /api/agent/design-system** [design-system:read] — Get tenant's design system tokens + CSS.
- **PATCH /api/agent/design-system** [design-system:write] — Update design system tokens.
- **DELETE /api/agent/design-system** [design-system:write] — Remove design system.
- **GET /api/agent/components** [design-system:read] — List components. Query: ?category=&q=
- **POST /api/agent/components** [design-system:write] — Create component manually.
- **POST /api/agent/components/generate** [design-system:write] — AI-generate component using design system. Body: { prompt, category? }. 15¢.
- **GET /api/agent/components/{id}** [design-system:read] — Get component details.
- **PATCH /api/agent/components/{id}** [design-system:write] — Update component.
- **DELETE /api/agent/components/{id}** [design-system:write] — Delete component.

### Design & Branding

- **GET /api/agent/site** [site:read] — Get site settings (theme, branding, custom HTML/CSS/JS, social links, AI config).
- **PATCH /api/agent/site** [site:write] — Update settings. Theme: layoutTemplate (preset only). Branding: logoUrl, headerHtml, footerHtml, customCss, customJs. Trust tiers: customCss requires tier 1+; headerHtml, footerHtml, customJs require tier 2+. DEPRECATED: themeConfig is no longer accepted — use the design system API (POST /api/agent/design-system/generate or PATCH /api/agent/design-system) for colors, fonts, spacing, and dark mode.
- **GET /api/agent/theme-info** [site:read] — Active CSS variables with current values, fonts, utility classes.
- **GET /api/agent/themes** [site:read] — List preset themes with colors, fonts, and variants.

### Email & Distribution

- **GET /api/agent/contacts** [contacts:read] — List contacts. Query: ?page=1&limit=50&status=ACTIVE&tag=newsletter&q=search
- **POST /api/agent/contacts** [contacts:write] — Create contact. Body: { email, firstName?, lastName?, tags?, metadata? }
- **GET /api/agent/campaigns** [campaigns:read] — List campaigns. Query: ?type=BROADCAST&status=DRAFT
- **POST /api/agent/campaigns** [campaigns:write] — Create campaign. Body: { name, emailSubject, emailBody, scheduledAt?, audienceFilters? }. 2¢ + 1¢ per email sent.
- **POST /api/agent/campaigns/{id}/send-now** [campaigns:send] — Trigger immediate dispatch to the configured audience. 2¢ + 1¢ per recipient. Returns { campaignId, recipients, sent, failed }. Insufficient credits → 402; campaign reverts to draft.
- **POST /api/agent/email/templates/generate** [email-templates:write] — AI-generate inbox-safe HTML email template. Body: { prompt, subject?, preheader?, ctaText?, ctaUrl?, category? }. 30¢.
- **GET /api/agent/webhooks** [webhooks:read] — List webhooks with delivery counts.
- **POST /api/agent/webhooks** [webhooks:write] — Create webhook. Body: { url, events: [...] }. Returns HMAC secret (shown once). Requires trust tier 1+.
- **DELETE /api/agent/webhooks?id={id}** [webhooks:write] — Delete webhook.

### SEO & Discovery

- **GET /api/agent/seo/audit** [seo:read] — SEO audit. Query: ?slug=article-slug&limit=100. Scores: retrieval, AEO, geo, technical.
- **POST /api/agent/seo/generate** [seo:write] — AI SEO generation. Body: { articleId }. Returns headlines, FAQs, keywords. 10¢.
- **POST /api/agent/images/suggest** [images:write] — Image suggestions. Body: { mode: "stock"|"ai", summary }. 10¢.
- **GET /api/agent/sitemap-entries** [seo:read] — Sitemap: noIndex flag, published articles/pages.
- **PATCH /api/agent/sitemap-entries** [seo:write] — Update sitemap. Body: { noIndex?, blogUrlPattern? }

### Data Collection

- **GET /api/agent/forms** [forms:read] — List forms. Query: ?status=ACTIVE
- **POST /api/agent/forms** [forms:write] — Create form. Body: { title, slug, fields: [{ name, type, label, required? }] }
- **GET /api/agent/forms/{id}** [forms:read] — Get form with submission count.
- **PATCH /api/agent/forms/{id}** [forms:write] — Update form.
- **DELETE /api/agent/forms/{id}** [forms:write] — Delete form + submissions.
- **GET /api/agent/forms/{id}/submissions** [forms:read] — List submissions. Query: ?page=1&limit=50
- **POST /api/agent/forms/{id}/submissions** [forms:write] — Submit data. Auto-creates contact on email. Triggers form:submitted webhook.
- **GET /api/agent/articles/{id}/analytics** [analytics:read] — Analytics: views, 7/30-day trends. Use id="top" for leaderboard.

### Infrastructure

- **GET /api/agent/domains** [site:read] — List hostnames and canonical host.
- **POST /api/agent/domains** [domains:write] — Add hostname. Body: { hostname }. Requires trust tier 1+.
- **DELETE /api/agent/domains?hostname={hostname}** [domains:write] — Remove hostname (cannot remove last). Requires trust tier 1+.
- **GET /api/agent/jobs** [jobs:read] — List async jobs. Query: ?status=PENDING|PROCESSING|COMPLETED|FAILED&limit=20
- **POST /api/agent/jobs** [jobs:write] — Create async AI job. Body: { action, resourceId?, payload? }
- **GET /api/agent/jobs/{id}** [jobs:read] — Get job status + result. Poll until COMPLETED or FAILED.
- **GET /api/agent/usage** [usage:read] — Usage stats. Query: ?month=2026-03&logs=20
- **GET /api/agent/whoami** [(none)] — Key info, scopes, tenant, credits, usage.

## OAuth 2.0

Full OAuth 2.0 with PKCE support for third-party integrations.

- **POST /api/oauth/register** — Dynamic client registration. Body: `{ client_name, redirect_uris, scope, tenant_id }`
- **GET /api/oauth/authorize** — Authorization. Query: `?response_type=code&client_id=...&redirect_uri=...&scope=...&state=...&code_challenge=...&code_challenge_method=S256`
- **POST /api/oauth/token** — Token exchange. Body: `grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...`
- **POST /api/oauth/revoke** — Revoke token. Body: `{ token: "oat_..." }`
- **GET /.well-known/oauth-authorization-server** — Server metadata (RFC 8414)

## MCP (Model Context Protocol)

Endpoint: `POST https://plgd.ai/api/mcp`
Transport: Streamable HTTP (stateless). Auth: same X-Agent-Key or Bearer token.

69 tools available, filtered by key scopes. Every action in this document is also available as an MCP tool.

Tools: list_articles, create_article, get_article, update_article, delete_article, batch_create_articles, run_story_pipeline, list_pages, create_page, get_page, update_page, render_page, list_revisions, restore_revision, get_site, update_site, get_theme_info, list_themes, list_navigation, create_navigation_item, update_navigation_item, delete_navigation_item, list_redirects, create_redirect, delete_redirect, generate_creative, refine_creative, list_creatives, get_creative, generate_design_system, get_design_system, update_design_system, delete_design_system, list_components, create_component, generate_component, get_component, update_component, delete_component, list_contacts, create_contact, list_campaigns, create_campaign, get_article_analytics, list_domains, add_domain, remove_domain, get_sitemap, update_sitemap, list_webhooks, create_webhook, delete_webhook, list_forms, create_form, get_form, update_form, delete_form, list_form_submissions, submit_form, list_jobs, create_job, get_job, list_ideas, generate_ideas, seo_audit, seo_generate, suggest_images, get_usage, whoami

## Discovery

- OpenAPI Spec: https://plgd.ai/api/openapi.json
- MCP Server: https://plgd.ai/api/mcp
- OAuth Metadata: https://plgd.ai/.well-known/oauth-authorization-server
- This file: https://plgd.ai/llms-full.txt
- Summary: https://plgd.ai/llms.txt

---
Generated for plgd
Last updated: 2026-06-09T23:34:49.978Z