API reference

GET /health

Liveness

No key: anyone can call it.

Responses

• 200 {ok, service, commit, builtAt, wave}: commit is the full SHA this build was made from and builtAt its build time (null for a local run); wave is a fixed legacy value

GET /openapi.json

This document

No key: anyone can call it.

Responses

• 200 OpenAPI 3.1

GET /.well-known/agent-card.json

A2A agent card (A2A 0.3.0, discovery only): its skills are the MCP tools/list, and a required extension names the MCP endpoint; there is no A2A task endpoint

No key: anyone can call it.

Responses

• 200 {protocolVersion, name, description, url, capabilities: {streaming: false, extensions: [{uri, required, params: {url, protocolVersion}}]}, securitySchemes, security, skills}

GET /.well-known/agent.json

The same A2A agent card at its pre-0.3.0 path, which A2A clients still probe (W5-D4)

No key: anyone can call it.

Responses

• 200 the document /.well-known/agent-card.json serves

GET /.well-known/mcp.json

MCP Registry server.json for this deployment (schema https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json, W5-D4): the remote MCP endpoint and how to authenticate to it

No key: anyone can call it.

Responses

• 200 {$schema, name, title, description, version, websiteUrl, remotes: [{type: streamable-http, url, headers: [{name: Authorization, isRequired, isSecret, value, variables}]}]}

GET /.well-known/oauth-protected-resource

RFC 9728 Protected Resource Metadata for the MCP endpoint (root well-known URL; E2.6)

No key: anyone can call it.

Responses

• 200 {resource, authorization_servers, scopes_supported, bearer_methods_supported}
• 404 mcp_oauth_not_configured (HEYCMO_MCP_OAUTH_ISSUER unset)

GET /.well-known/oauth-protected-resource/v1/mcp

RFC 9728 Protected Resource Metadata for the MCP resource (path-specific; the URL every MCP 401 names)

No key: anyone can call it.

Responses

• 200 {resource, authorization_servers, scopes_supported, bearer_methods_supported}
• 404 mcp_oauth_not_configured

GET /.well-known/oauth-protected-resource/v1/cli

RFC 9728 Protected Resource Metadata for the CLI resource that heycmo login signs in to (E5, #383)

No key: anyone can call it.

Responses

• 200 {resource, authorization_servers, scopes_supported, bearer_methods_supported, resource_name}
• 404 cli_oauth_not_configured (MCP OAuth is off)

GET /oauth/heycmo-cli.json

The CLI's OAuth Client ID Metadata Document: a public client with loopback redirects (E5)

No key: anyone can call it.

Responses

• 200 {client_id, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method, scope}
• 404 cli_oauth_not_configured

GET /cli/login

What heycmo login needs: the CLI resource, the authorization server, the client id and the scopes (E5)

No key: anyone can call it.

Responses

• 200 {resource, authorizationServer, clientId, scopes}
• 404 cli_oauth_not_configured

GET /.well-known/openai-apps-challenge

ChatGPT app domain verification (W3-3): the token OpenAI issued, as plain text, from HEYCMO_OPENAI_APPS_DOMAIN_VERIFICATION

No key: anyone can call it.

Responses

• 200 the verification token (text/plain, no-store)
• 404 no token configured

GET /

W3-7: a hosted landing page on a tenant's own hostname, served only to requests the variant edge forwards with its shared secret (x-heycmo-edge). The visitor's variant, a first-party cookie (__Host-hcv) for a new visitor, a strict CSP; the control and no cookie for Global Privacy Control or Do Not Track. Elsewhere, for a restricted workspace, or while the operator's landing-pages switch is engaged: 404

No key: anyone can call it.

Responses

• 200 text/html
• 404 nothing published on this hostname, taken down, or not through the edge
• 429 rate limited (the visitor's address)

POST /_hc/v/{test}

W3-7: a hosted page's exposure beacon (through the variant edge only), for the test that produced the page: enrols the visitor once while that test still serves and allocates; a beacon from a page of a test no longer served enrols nothing. Always 204

No key: anyone can call it.

Parameters

Responses

• 204 nothing to read
• 404 not a test reference
• 413 body too large

GET /_hc/c/{test}/{label}/{index}

W3-7: a hosted page's goal link (through the variant edge only), bound to the test that produced the page: while that test still serves, records the conversion for an enrolled visitor inside their window and redirects to its approved target; once it is taken down or replaced, 404 (never another test's target)

No key: anyone can call it.

Parameters

Responses

• 302 to the approved goal URL (no-store)
• 404 no such link, or its test is no longer served
• 429 rate limited (the visitor's address)

GET /v1/activity/sends

Emails HeyCMO sent or rehearsed after an approval, newest run first (ordered by when they ran, before the limit); more says older sends exist

Scope: read.

Parameters

Responses

• 200 {sends: [{id, loop, actionType, to, subject, at, dryRun}], limit, more}

GET /v1/activity/week

What HeyCMO did in the last 7 days, for the home's "This week" (B6): loop runs, items staged, decisions, emails sent (the sends /v1/activity/sends lists in the window: live, rehearsed, not recorded), external writes applied and reversals, payments recovered per currency

Scope: read.

Responses

• 200 {since, until, days, loops: {runs, loopsRun, runsWithFindings, failedRuns}, staged, decided: {approved, declined}, sends: {total, live, rehearsed, unrecorded}, writes: {applied, reversals}, recovered: [{currency, cents, count, emailDrivenCents}]}

GET /v1/agents

Agents and keys (admin): HeyCMO's MCP address, whether people sign in with an account (then no key approves), whether an AI assistant (MCP OAuth) and the terminal (heycmo login) can sign in here, the assistants and terminal sign-ins that reached this workspace (each OAuth client and member, first and last seen, most recent first), and what went out in the last seven days by who decided it. API keys stay at GET /v1/api-keys

Scope: admin.

Responses

• 200 { mcpUrl, signIn: { people, assistants, terminal }, connections: [{ id, kind: mcp|cli, clientId, person, firstSeenAt, lastSeenAt }], week: { from, to, shipped, byPeople, standing, other, edited } }
• 403 admin scope required

GET /v1/api-keys

List API keys (admin): id, label, scopes, status, createdAt, expiresAt, lastUsedAt, revokedAt, lastFour (the secret's last four characters; null for a key minted before they were kept), creator (who created it: {kind: person, email} for a member of this workspace, {kind: key, name} for a key, or null) — never the secret

Scope: admin.

Responses

• 200 {keys}
• 403 admin scope required

POST /v1/api-keys

Create an API key (admin). The secret is in this response only

Scope: admin.

Request body (application/json)

Responses

• 201 {key, secret, note}
• 400 bad body
• 403 admin scope required, or a scope the caller does not hold (scope_escalation)
• 429 credential change rate limit

POST /v1/api-keys/{id}/rotate

Rotate an API key (admin): new secret, same label and scopes; the old key is revoked at once (no grace window)

Scope: admin.

Parameters

Request body (application/json)

Responses

• 200 {key, secret, rotated, note}
• 404 no such key in this tenant
• 409 key already revoked

DELETE /v1/api-keys/{id}

Revoke an API key (admin). Idempotent; refuses the last active admin key of a tenant with no Clerk organisation

Scope: admin.

Parameters

Responses

• 200 {revoked, alreadyRevoked, key}
• 404 no such key in this tenant
• 409 last_admin_credential

POST /v1/approve/{id}

Approve staged action (MCP approve_action dispatches here for a signed-in session only)

Approval is a person's decision. Where people sign in (Clerk or AuthKit), only a signed-in session approves; a machine key changes nothing and gets 403 {code: human_approval_required, approved: false, approveUrl} for a person to open in the dashboard inbox. Declining stays open to keys.

Scope: approve.

Parameters

Request body (application/json)

Responses

• 200 executed or blocked
• 400 invalid approval body
• 403 scope, or human_approval_required with approveUrl (a machine key where people sign in)
• 409 stale preview: human_preview_required (no operationHash) or approval_stale_or_resolved (the item changed since it was shown); or an unmet approval prerequisite. Nothing is approved or executed

GET /v1/audit

Audit log (get_audit_log)

Scope: read.

Parameters

Responses

• 200 {items, count, summary?: {total, today, matching, since}}: entries newest first, with each row's prevHash and rowHash, and by, who did it: {kind: api_key|mcp|cli|person, person, clientId, key: {id, name, lastFour}}, or null for HeyCMO on its own, a notice from a connected tool, or an entry written before who was recorded. clientId is the assistant's or the terminal's OAuth client; person (the address) and key are given to admin readers only. The summary (first page only, not with cursor) counts the whole trail, today's entries and the entries matching the filters.
• 400 tier is not an integer, a time is not an ISO date and time, cursor is not an entry id, by names an unknown kind, or notKey is not a key id or comes without by=api_key

GET /v1/audit/filters

Tenant-wide audit filter values

Scope: read.

Responses

• 200 {loops, actions}

GET /v1/audit/verify

Recompute this tenant's audit hash chain and check it against its daily anchors (E2.4)

Scope: read.

Responses

• 200 ok, state, first failing row (failures[]), purges, anchors

GET /v1/audit/last-check

The daily check of this tenant's audit chain (Design v2 History: "Last checked automatically at 06:00"): the same walk as /v1/audit/verify, run after the daily anchor

Scope: read.

Responses

• 200 { checkedAt, state: verified|failed|unchained, entries, failure: { kind, seq } | null }, or { checkedAt: null } before the first check

GET /v1/audit/export

Audit evidence export: NDJSON header, pre-chain rows, chained rows with hashes (E2.4)

Scope: read.

Responses

• 200 application/x-ndjson

GET /v1/autonomy

Graduated autonomy (E4.6): eligibility per loop/action type with reasons, grant state, plan entitlement, the signed threshold set, terms and history

Scope: read.

Responses

• 200 {enabled, readOnly, plan, thresholdSet, bar, terms, policyDiagnostics, pairs, history, floor}; bar is the thresholds every pair is measured against {default, channels, actionTypes, incidents} (the signed set's rules, or the proposed defaults before one is signed); the payment-recovery send pair (failed-payment-dunning, send) also carries touchPlan {reminderDay, urgentDay, finalDay, includeRetrying, preDunning, summary}: the touch plan its grant covers (issue #232); design v2: each pair's lastEdit {at, fields, subject: {before, after} | null, added, removed} | null, the latest edit of a decision its record counts (a card still waiting is left out) from the feedback ledger (scrubbed: the words the edit added and took out, at most 120 characters each)

GET /v1/autonomy/eligibility

Autonomy eligibility from real decisions (approval rate, edit rate, observation days, time to decide) and incidents, against the operator-signed thresholds

Scope: read.

Responses

• 200 {evaluatedAt, thresholdSet, pairs: [{loop, actionType, stats, incidents, rule, eligible, reasons}]}

POST /v1/autonomy/request

Request autonomy for one eligible loop/action type (admin; OS or Alpha plan). The platform operator approves

Scope: admin.

Request body (application/json)

Responses

• 200 state requested
• 400 terms not acknowledged or bad body
• 402 plan does not include autonomy (Operator, trial, restricted)
• 409 not eligible, thresholds unsigned, autonomy disabled, or not requestable from the current state

POST /v1/autonomy/revoke

Withdraw a request or end a grant now (admin); idempotent. /v1/autonomy/demote is the same route

Scope: admin.

Responses

• 200 {state: gated, changed}

GET /v1/billing/prices

HeyCMO platform tiers + Checkout availability

Scope: read.

Responses

• 200 tiers + checkoutEnabled

GET /v1/billing/status

HeyCMO plan, billing status, period end, when a plan set to cancel ends, entitlements, usage vs allowance, model spend vs its ceiling, suspension, no-card trial

Scope: read.

Responses

• 200 plan + effectivePlan + currentPeriodEnd + cancelAt (when a subscription set to cancel ends: Stripe cancel_at or cancel_at_period_end; null while it renews) + entitlements + usage + modelSpend (todayCents, weekCents, dailyCeilingCents, weeklyCeilingCents, dailySource, weeklySource) + trial (endsAt, daysLeft, ended, pausedAt, pausedDays: W4-D2, the trial clock stops while a go-live request waits for HeyCMO and the end moves on by the time it waited) + trialPausedDays (0 when not on a trial) + restriction; addons.geoDaily; B6: plans ([{plan, maxEnabledLoops, maxLoopStage, stageExemptLoops, allowance, overageBilled, autonomy, hostedLandingPages, geoDaily}]: each plan's gates as the entitlement functions enforce them)

POST /v1/billing/checkout

Create Stripe Checkout Session (Operator/OS; admin)

Scope: admin.

Responses

• 200 url + sessionId; the same request again gets the same open session (one per tenant), another plan or return URL expires it in Stripe first
• 400 return URL not on the public site or dashboard origin
• 409 subscription_exists — manage it in the Customer Portal (a no-card trial is not a subscription: checkout converts it); checkout_completed — the open session was just paid and its subscription is about to apply
• 503 platform Stripe not configured

POST /v1/billing/portal

Create Stripe Customer Portal session {returnUrl?} (admin)

Scope: admin.

Responses

• 200 url
• 400 return URL not on the public site or dashboard origin
• 409 no_billing_customer — start with checkout
• 503 platform Stripe not configured

POST /v1/brand/draft

Draft the brand kit (colours, fonts, voice) from the site and merge it into the stored kit (execute). A draft that adds nothing (no model, HEYCMO_DRAFTER=template, or nothing found) comes back with a warning

Scope: execute.

Request body (application/json, required)

The site to read: siteUrl, as POST /v1/onboarding/bootstrap names it, or url (accepted too; both given must name the same address, compared as URLs: case of scheme and host, default port, fragment and a trailing slash do not count)

Responses

• 200 {kit, draftSource: llm|template|template-fallback, warning?}: warning only when the draft added nothing to the kit
• 400 neither siteUrl nor url, or two different sites: {error} says which field to send

GET /v1/briefs

The weekly briefs, newest first (read, at most 12): each with its status, when the weekly review wrote it, the week it covers (the seven days up to then, however much later it was approved), when it was sent (null until then), when it was last acknowledged, and how many actions went out that week (acknowledged reports, approved drafts and run-now requests are not counted)

Scope: read.

Responses

• 200 { briefs: [{ id, status, generatedAt, sentAt, week: { from, to }, acknowledgedAt, shipped }] }

GET /v1/briefs/{id}

One weekly brief with its week (read): its payload (the digest and the movers), what went out that week grouped by action type and job (how many a person edited first, how many a standing approval sent), and the week's runs (how many, how many completed with nothing to do, the last failed ones)

Scope: read.

Parameters

Responses

• 200 { id, loop, status, generatedAt, sentAt, week, acknowledgedAt, payload, shipped: { total, edited, standing, groups }, checks: { runs, nothingFound, failed } }
• 404 brief not found

POST /v1/briefs/{id}/ack

Acknowledge a completed weekly brief idempotently

Scope: approve.

Parameters

Responses

• 200 acknowledgement recorded
• 409 brief not final

GET /v1/card-update

W5-A1: a recovery email's 1-click card-update link (unauthenticated; HMAC-signed by HeyCMO, expires 60 days after drafting). Creates a Stripe Billing Portal payment_method_update session at the click (governed stripe.createBillingPortalSession, Tier 1; a session URL is short-lived, so none is created at drafting) and redirects to it; otherwise to the fallback the link was signed with (the invoice's hosted page, or the portal's login page). The session sets only the customer's default card, so a link whose subscription names a card of its own, or cannot be read, also goes to the fallback; so does one whose subscription no longer charges (cancelled, expired, ended or unpaid), and any link of a workspace that is not active (suspended, deleted or billing-restricted). A dry-run workspace creates nothing and says so

Called by the provider and signed with its secret; API keys are not accepted.

Parameters

Responses

• 200 text/html: dry run (nothing created in Stripe), or no fallback (reply to the email)
• 303 to the Stripe Billing Portal session, or to the fallback (no-store, no referrer)
• 400 text/html: not a valid card-update link (forged, cut, or signed before SECRETS_MASTER_KEY was rotated); nothing in it is followed
• 410 text/html: the link expired and has no fallback
• 429 rate limited with no fallback: the client's address (60 opens a minute; text/plain for a link that does not verify, else the reply page), or the link's session budget (10 opens in 10 minutes, every open counted). A link that verifies and has a fallback is a 303 to it instead
• 503 text/html: the card update page failed after the link verified and the link has no fallback (reply to the email)

GET /v1/connect

Stripe/Resend connection state and this tenant's webhook URLs and events

Scope: read.

Responses

• 200 {stripe, resend}

POST /v1/connect/stripe

Validate a restricted Stripe key, store it, and register the attribution webhook (signing secret stored); manual steps when the key cannot manage webhooks

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, mode, keyStored, webhook: {status: created|reused|manual, url, events, …}, webhookSecretStored}
• 422 key invalid or cannot read invoices — nothing stored
• 502 Stripe unreachable — nothing stored

POST /v1/connect/resend

Validate a Resend API key, store it, and register the event webhook (signing secret stored); manual steps for a sending-only key

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, access, keyStored, webhook: {status: created|reused|manual, url, events, …}, webhookSecretStored}
• 422 key invalid — nothing stored
• 502 Resend unreachable — nothing stored

POST /v1/connect/sendgrid

Validate a SendGrid API key (GET /v3/scopes: mail.send required), store it, and set up the signed Event Webhook (verification key stored); manual steps when the key cannot manage webhooks

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, keyStored, region, webhook: {status: created|reused|manual, url, events, …}, webhookSecretStored (events can arrive: key stored, webhook enabled), legacyTemplate (on|off|null: marketing waits unless off), sender, emailProvider, switched, warnings}
• 409 email_provider_switch_required — another connected provider sends every email; nothing changed. sendgrid_key_replaced — another SendGrid key was stored while this connect ran; nothing more this key showed was kept
• 422 key invalid or without mail.send — nothing stored
• 502 SendGrid unreachable — nothing stored

GET /v1/connect/esp

Which ESPs are connected (Customer.io, Loops, Klaviyo), the esp write-channel posture and the attestation version; no provider call

Scope: read.

Responses

• 200 {providers: [{provider, connected, credentialSource, writes, region?}], writeChannel, attestationVersion}

POST /v1/connect/customerio

Validate a Customer.io App API key (GET /v1/workspaces; both regions probed when none is given) and store it

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, region, workspace, keyStored}
• 422 key invalid — nothing stored
• 502 Customer.io unreachable — nothing stored

POST /v1/connect/loops

Validate a Loops API key (GET /api/v1/api-key) and store it

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, team, keyStored}
• 422 key invalid — nothing stored
• 502 Loops unreachable — nothing stored

POST /v1/connect/klaviyo

Validate a Klaviyo private API key (accounts:read, metrics:read) and store it; Klaviyo is read-only

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, account, keyStored, writes: none}
• 422 key invalid or missing a scope — nothing stored
• 502 Klaviyo unreachable — nothing stored

GET /v1/connect/reviews

Which review sources are connected (G2 read only, App Store Connect, Google Play), their app/product ids and the reviews write-channel posture; no provider call

Scope: read.

Responses

• 200 {providers: [{provider, label, connected, target, replies}], writeChannel, deferred}

POST /v1/connect/g2

Validate a G2 API token against the product (GET /api/v1/products/{id}) and store it; G2 is read only

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, product, productId, keyStored}
• 422 token invalid, no access to the product, or product not found — nothing stored
• 502 G2 unreachable — nothing stored

POST /v1/connect/appstoreconnect

Validate an App Store Connect API key (ES256 JWT; GET /v1/apps/{id} and a customer-review read) and store it

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, app, appId, keyStored}
• 422 key invalid, its role cannot read reviews, or app not found — nothing stored
• 502 App Store Connect unreachable — nothing stored

POST /v1/connect/googleplay

Validate a Google Play service account (token exchange at Google's endpoint, one reviews.list call) and store it

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, packageName, serviceAccount, keyStored}
• 422 not a service-account key, or it lacks the "Reply to reviews" permission — nothing stored
• 502 Google unreachable — nothing stored

POST /v1/connect/sanity

W2-8: check a Sanity connection (a query on the dataset and a dry-run write) and store it as the sanity secret for CMS publishing

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, platform, target, detail, pages, keyStored}
• 400 not a Sanity connection
• 422 token invalid, lacking a permission, or the project/dataset not found — nothing stored
• 502 Sanity unreachable — nothing stored

POST /v1/connect/contentful

W2-8: check a Contentful connection (content types, mapped field types, locale) and store it as the contentful secret for CMS publishing

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, platform, target, detail, pages, keyStored}
• 400 not a Contentful connection
• 422 token invalid, a content type, field or locale missing or of the wrong type — nothing stored
• 502 Contentful unreachable — nothing stored

POST /v1/connect/git

W2-8: check a GitHub repository connection (repository, base branch, content directories) and store it as the git secret; pages are proposed as pull requests HeyCMO never merges

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, platform, target, detail, pages, keyStored}
• 400 not a Git connection (a directory outside the repository, a hidden directory or a bad branch is refused)
• 422 token invalid or without access, branch or directory missing — nothing stored
• 502 GitHub unreachable — nothing stored

GET /v1/connect/product-analytics

Which product-analytics sources are connected (PostHog, Mixpanel, Amplitude), the one the daily collection reads and the event names; no provider call

Scope: read.

Responses

• 200 {providers: [{provider, label, connected, credentialSource, target, region, oauthAvailable?}], collecting, provider, events: {active, activation, trial}, reads}

POST /v1/connect/posthog

Validate a PostHog personal API key against the project (GET /api/projects/{id}/ and a SELECT 1 HogQL query) and store it; read only

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, provider, project, projectId, region, keyStored}
• 422 not a personal API key, unknown project, or missing project:read / query:read — nothing stored
• 502 PostHog unreachable — nothing stored

POST /v1/connect/mixpanel

Validate a Mixpanel service account against the project (a one-day segmentation) and store it; read only

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, provider, projectId, region, keyStored}
• 422 not a service account, unknown project, or no access to it — nothing stored
• 502 Mixpanel unreachable — nothing stored

POST /v1/connect/amplitude

Validate an Amplitude API key and secret key (one day of active users) and store them; read only

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, provider, region, keyStored}
• 422 the key pair is refused — nothing stored
• 502 Amplitude unreachable — nothing stored

POST /v1/connect/segment

Create (or rotate) the Segment destination's shared secret; returns it once with the per-tenant webhook URL (admin, audited)

Scope: admin.

Responses

• 200 {ok, provider, webhookUrl, sharedSecret (shown once), rotated, setup}
• 429 too many credential changes

GET /v1/connect/github-release

The GitHub release webhook (W5-D2): whether its secret is stored, the URL to paste into GitHub, the last delivery, and the latest release launches (status, Marketing Factory run, cards staged)

Scope: read.

Responses

• 200 {configured, webhookUrl, events, lastDeliveryAt, lastDeliveryEvent, launchesPerDay, launchesToday, launches: [{origin, repo, tagName, url, status, runId, stage, stagedCount, attempts, reason, startedAt, finishedAt}], blocked: [{origin, repo, tagName, url, block, reason, receivedAt}]}; status is started, awaiting_approval, completed, declined, bailed, failed, blocked or interrupted, and follows the run once a person decides it; blocked lists the releases a gate (kill switch, restriction, no plan, daily cap) kept from starting that have not launched since

POST /v1/connect/github-release

Create (or rotate) the GitHub release webhook's secret; returns it once with the per-tenant webhook URL and the setup steps; the old secret stops working at once (admin, audited without the secret)

Scope: admin.

Responses

• 200 {ok, provider, webhookUrl, secret (shown once), rotated, contentType, events, setup}
• 403 read-only key
• 429 too many credential changes

GET /v1/connections

OAuth connection status per provider (ga4, gsc, googleads, hubspot; bing, webflow, postmaster, meta, linkedin, x, posthog, attio, pipedrive, microsoftads, canva and twenty when the operator configured their integrations): status, credential source (nango|secret|none), readiness, granted and missing scopes, chosen resource — never a token. crmProvider: the CRM account context reads (hubspot|attio|pipedrive|twenty|null)

Scope: read.

Responses

• 200 {configured, crmProvider, providers}

POST /v1/connections/{provider}/session

Create a Nango Connect session for this tenant and one provider (admin); a reconnect session when a connection exists. The connection is usable once the Nango webhook reports it. One CRM per tenant (hubspot, attio, pipedrive, twenty — Twenty by an API key the tenant pastes into the Nango Connect page): connecting a CRM while another is connected needs {switchProvider: true}; the previous CRM connection is deleted once Nango confirms the new one

Scope: admin.

Parameters

Request body (application/json)

Responses

• 201 {provider, integrationId, mode: connect|reconnect, token, connectLink, expiresAt}
• 404 unknown_provider
• 409 crm_switch_required — another CRM is connected; {currentProvider, requestedProvider}, nothing changed
• 429 credential change rate limit
• 502 nango_unavailable — nothing changed
• 503 oauth_not_configured (NANGO_SECRET_KEY unset)

PATCH /v1/connections/{provider}

Choose the GA4 property, Search Console site, Google Ads customer, Meta resources or LinkedIn Page/ad account/own profile the connection reads and writes (admin). Meta: page:<id>, ig:<id> and/or adaccount:<id> joined by |, merged onto the current choice; LinkedIn (E4.2): {organizationId?, adAccountId?, personId?} (null clears one; personId — W2-2 — the connected member as a post author) or a picker resourceId, merged into its choice. X (W2-2) is refused: its account is the one X reports, recorded by the resources listing. Microsoft Advertising (W3-4): account:<id>,customer:<id>, an ad account and the customer it belongs to, as the resources listing offers them

Scope: admin.

Parameters

Request body (application/json)

Responses

• 200 {ok, provider, resourceId}
• 400 invalid_resource
• 409 not_connected
• 422 resource_not_applicable (hubspot, attio, pipedrive, twenty); resource_from_connection (x)

DELETE /v1/connections/{provider}

Disconnect: delete the Nango connection (admin). Idempotent

Scope: admin.

Parameters

Responses

• 200 {ok, provider, deleted, status: not_connected}
• 502 nango_unavailable — nothing changed
• 503 oauth_not_configured

GET /v1/connections/{provider}/resources

GA4 properties, Search Console sites, Google Ads customers, Meta Pages / linked Instagram accounts / ad accounts, LinkedIn Pages, ad accounts and the connected member's own profile (ids organization:<id> / sponsoredAccount:<id> / person:<id>), the connected X account (its user id, a billed X read), or the Microsoft Advertising accounts the connected user manages (ids account:<id>,customer:<id>) the connection can read; the only one (Meta, LinkedIn: of each kind) is chosen when none is — never the LinkedIn member, whom only the tenant chooses; the X account is always the one X reports

Scope: read.

Parameters

Responses

• 200 {provider, resources: [{id, label}], selected, grantedPermissions? (meta)}
• 409 not_connected
• 502 provider_unavailable

POST /v1/content/drafts

"Draft this" on an SEO content brief, or "Draft refresh" (pageUrl) on a content refresh brief (#233, execute): T-01 writes the article (1,200–2,000 words) from the brief, or from the page as WordPress reports it, through the metered model client; the on-page checklist runs (title 30–60 characters, no H1 in the body, the search in the title and first paragraph, at least 2 links to the site, outside links only from the inputs, a title no other page has, the length), with one retry for a failed check; it is staged as a cms.publishPost draft (a new page) or a cms.updatePost edit (a page that exists, WordPress only). Nothing is published; a card already staged for the same source, CMS and page is answered without a model call, unless it ended without the live result (declined, failed or blocked: drafted again; only rehearsed: the same article on a fresh card, without a model call)

Scope: execute.

Request body (application/json)

Responses

• 200 a draft of this source for that CMS, page and search was already staged (alreadyStaged: true; its checks run again)
• 201 {stagedActionId, alreadyStaged: false, actionType: cms.publishPost | cms.updatePost, kind: new_page | optimize_page | refresh, sourceActionId, title, words, checks: [{id, ok, detail}], checksPassed, editorialItemId, channels, leftOut, posture}
• 400 invalid body, or the write refused the article at staging
• 404 not_found — source action not found (another workspace's too)
• 409 source_declined, cms_not_connected, cms_paused (the cms kill switch stopped the read of the page), unsupported_platform (editing a page needs WordPress), page_not_found, or no_model (no model provider is configured; nothing was staged)
• 422 not_draftable — not an SEO content brief or a content refresh brief, a refresh brief without one of its pages as pageUrl, a query the brief does not hold, or a brief with no page to rewrite; page_not_rewritable — the page holds what a whole-body rewrite could not keep (images, embeds, tables, forms, scripts, WordPress blocks other than text, shortcodes) or more text than the draft reads (16,000 characters); the message names it, nothing was staged

POST /v1/content/publish

Stage the publish of a CMS draft HeyCMO saved and that was applied live (#233, execute): one cms.publishPost with the same post and status published, its own approval (asked again, the same card; a fresh one once it was declined, failed, blocked or only rehearsed). Approving it publishes the post; the IndexNow submission of its address is then proposed as its own card

Scope: execute.

Request body (application/json)

Responses

• 200 the publish of this draft was already staged
• 201 {stagedActionId, alreadyStaged: false, actionType, channels, target, preview, draftActionId, editorialItemId, posture}
• 404 not_found — draft not found
• 409 not_a_draft (not a CMS draft post HeyCMO saved) or not_applied (the draft is not in the CMS yet: approve it, with the cms channel live)

POST /v1/content/link-edits

Propose link edits from an internal-link report (#233, execute): for each page to link from (at most 3, WordPress), one sentence that names a target page gets a link to it — one cms.updatePost card per page, each its own approval. Pairs with no such sentence are listed, never guessed

Scope: execute.

Request body (application/json)

Responses

• 200 every card was already staged
• 201 {staged: [{pageUrl, stagedActionId, alreadyStaged, edits}], unmatched: [{from, to, reason}], channels, posture}
• 400 invalid body, or the write refused an edit at staging
• 404 not_found — source action not found
• 409 cms_not_connected, cms_paused (the cms kill switch stopped the read of a page), unsupported_platform (WordPress only) or page_not_found
• 422 not_draftable (not an internal-link report, or nothing to link) or nothing_to_change

GET /v1/content/snapshot

The content snapshot the content loops read (#233): its source (ingest = a partner push, which stays until the partner pushes again; first_party = derived weekly from Search Console page clicks over 90 days against the 90 before, GA4 page views and the connected WordPress site's posts), when, from what (with notes on what was not read), when the next weekly derivation is due, and its busiest pages

Scope: read.

Responses

• 200 {source, updatedAt, pages, derived: {at, windowDays, gsc, ga4, cms, notes} | null, nextRefreshAfter, topPages: [{url, title, traffic90d, trafficPrev90d, position, pageViews90d, pageViewsPrev90d, lastRefreshedAt, sources}], losing: [the pages content-decay counts as losing visitors (at least 25% down on the 90 days before), the worst first, at most 25: {…topPages fields, drop, refresh: {briefActionId, briefStatus, briefAt, draftActionId, draftStatus, draftRehearsed: the edit ran as a rehearsal and changed nothing} | null}], losingTotal, links: design v2, the newest internal-linking report (internal_link_draft) of the last 45 days unless declined: {actionId, loop, status, at, linkTo: [{url, title}] (pages that get few links), linkFrom: [{url, title}] (the busiest pages; the first 3 are the ones POST /v1/content/link-edits edits), broken (internal links it found broken), drafts: [the cms.updatePost link edits staged from it, the newest per page: {actionId, url, title, links, anchors: [{text, href}] (the words each link goes on, a phrase the page already has, and the page it points to), status, rehearsed}]} | null}

POST /v1/content/snapshot/refresh

Derive the content snapshot now from Search Console, GA4 and the CMS, whatever its age (execute); never over a partner push. A page seen for the first time since the previous derivation is proposed for IndexNow (one card, its own approval)

Scope: execute.

Responses

• 200 {refresh: {status: derived, pages, updatedAt, derived, newUrls, indexNow} | {status: skipped, reason: partner_push | no_source | conflict, detail}, snapshot}

GET /v1/content/calendar

The editorial calendar (#233): one item per topic and week (Monday, UTC), from two weeks back (or from the week of from), with its channel, status (idea, briefed, drafted, published, dropped), the loop that first proposed it and every proposer since, and the brief, draft and publish cards. Items of earlier weeks that are not done come first: a brief or draft waiting on a person (briefed, drafted), and a published post or edit at a known address whose 56-day page readback is not in yet while the daily readback pass may still record it

Scope: read.

Parameters

Responses

• 200 {from, weeks, items: [{id, weekStart, topic, angle, channel, status, sourceLoop, sourceActionId, proposedBy, draftActionId, draftActionType: cms.publishPost (a draft post) | cms.updatePost (an edit of a page) | null, publishActionId, url, outcome: {readbacks?: [{windowDays, changeDay, clicks, impressions, position, clicksBefore, impressionsBefore, positionBefore, readiness, outcome, label}], geoGapsClosed?: [{promptId, prompt, runId, periodKey}]} | null, updatedAt}]} — outcome: the page readbacks of the published post or edited page (Search Console, 14/28/56 days) and the GEO citation gaps that closed after it went live; directional, never causal
• 400 weeks out of range, from not a calendar day, or since not a date and time

PATCH /v1/content/calendar/{id}

Drop an editorial item still to write, or bring a dropped one back as an idea (execute)

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 {item}
• 400 invalid body
• 404 not found (another workspace's item too)
• 409 the item cannot take that status (a published item is never dropped; only a dropped item comes back)

GET /v1/context/history

The product context's version history, newest first (read): each substantive write's version, the section it changed (null for the whole document), the reason, who proposed it (draft:<source>, api-key:<id>, loop:<id>, playbook:<id>) and who accepted it. Only the changelog is kept, not each version's body. limit 1-200, default 50. latest is each section's newest change (and the whole document's), however far back, so where a section came from does not depend on the limit

Scope: read.

Responses

• 200 { version, versions: [{ version, fromVersion, section, reason, proposedBy, acceptedBy, at }], latest: [same fields] }: version is the current one, null before the first context (when versions and latest are empty too); both lists newest first

POST /v1/context/draft

Draft the product context from the site (execute). A blank template (no model, or HEYCMO_DRAFTER=template) comes back with a warning; drafting again replaces an untouched template

Scope: execute.

Request body (application/json, required)

The site to read: siteUrl, as POST /v1/onboarding/bootstrap names it, or url (accepted too; both given must name the same address, compared as URLs: case of scheme and host, default port, fragment and a trailing slash do not count)

Responses

• 200 {version, bodyMd, summary, sections, draftSource: llm|template|template-fallback, warning?}: warning only for a template
• 400 neither siteUrl nor url, or two different sites: {error} says which field to send
• 409 a context that describes the product exists, or someone wrote in the blank template while HeyCMO drafted over it (nothing is overwritten): edit it with PUT /v1/context

GET /v1/conversions

W3-1 conversion send-back: the settings, each destination's readiness (Google Ads through the Data Manager API, LinkedIn through the Conversions API; the tenant's Stripe key is required) and mapping, the Stripe side (key stored, the endpoint's events, when to reconnect), whether sends are rehearsed, 30-day counts and the latest ledger rows — never an address, hash or click id

Scope: read.

Parameters

Responses

• 200 {dryRun, validateOnly, settings: {unknownConsent, destinations}, destinations: [{destination, label, ready, reason, account, mapped}], stripe: {keyStored, reason, events, note}, maxAttempts, stripeEvents, metadataKeys, counts30d, recent: [{id, destination, conversionType, status, dryRun, sourceObjectId, destinationRef, occurredAt, valueMinor, currency, identifierKind, adUserData, adPersonalization, consentSource, providerRequestId, reason, createdAt}], capture: {endpoint, liveModeOnly, liveModeNote, metadataKeys: {visitor, clickIds, utm, hosted}, cookies, touchRetentionDays, maxTouchesPerRequest, snippet, serverHelper}} (#235: first-party click capture)

PUT /v1/conversions/settings

Map a Google Ads conversion action and a LinkedIn conversion rule (ids as digit strings; null unmaps; fields not sent are kept) to each conversion type, and choose what an unknown ad_user_data consent does (admin, audited)

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, settings, destinations}
• 400 malformed body or id

POST /v1/conversions/consent

Record one customer's consent from the tenant's consent tool (source api), before the Stripe event it should apply to: by Stripe customer id or e-mail address (kept only as tenant-scoped tokens of its plain and its Google form); a denial from any source holds

Scope: execute.

Request body (application/json)

Responses

• 200 {ok, subject, source, adUserData, adPersonalization, tcfStringStored, updatedAt}
• 400 exactly one of customerId or email, and at least one consent field
• 503 consent by address needs the platform PII token key

POST /v1/conversions/click

#235 first-party click capture: the tenant's server sends the landings the capture snippet kept for one visitor (its random visitor id and up to 20 touches: when, the ad click ids and UTM tags, or the referring site). Kept under an HMAC token of the visitor id for 90 days; conversion send-back uses a captured Google or LinkedIn click id when a conversion's Stripe metadata names the visitor (heycmo_vid). Never logged or audited: the visitor id and click ids

Scope: execute.

Request body (application/json)

Responses

• 200 {ok, stored, duplicates, touches: [{source, medium, campaign, channelGroup}]} — the channel each touch resolves to; no id is returned
• 400 an unknown field, an invalid value, a time in the future or older than 90 days, or a touch with neither a click id, a UTM tag nor a referring site
• 403 read-only key
• 413 body larger than 16 KB
• 503 click capture needs the platform PII token key

GET /v1/creative/config

Creative studio (E4.4): settings, month-to-date generation usage against the budget, templates and sizes, the model allowlist (vetted, allowed, configured), and whether storage and C2PA signing are available (signer kind, trusted, and why not: a certificate without the C2PA claim-signing EKU, or outside its validity)

Scope: read.

Responses

• 200 settings, usage, availability, templates, models

PUT /v1/creative/config

Set creative settings (admin): enabled, monthlyBudgetCents (at or below the platform budget; null = platform default)

Scope: admin.

Responses

• 200 updated
• 400 invalid or unknown field, or above the platform budget

GET /v1/creative/assets

The creative gallery: signed draft assets with alt text, provenance, the ref an external-write operation carries, and a short-lived URL; design v2: usedIn [{actionId, loop, actionType, status, createdAt, rehearsed}], the cards whose payload references it (an assetId at any depth), made or edited since the oldest listed asset, newest first (at most 3), never their payload, and usedInCount, how many such cards in all

Scope: read.

Parameters

Responses

• 200 assets

GET /v1/creative/assets/{id}

One asset plus a live read-back: stored bytes re-hashed and the C2PA manifest re-validated, with its trust-list status (trustList)

Scope: read.

Parameters

Responses

• 200 asset, verification
• 404 not found

POST /v1/creative/templates/{id}/preview

Design v2 Images: a live preview of a brand-kit template at one size (default the template's first) as the copy is typed: rendered like a draft, but unsigned, never stored or metered, and scaled to at most 640 px; at most 60 a minute per workspace

Scope: read.

Parameters

Request body (application/json)

Responses

• 200 {image: data:image/webp;base64,…, templateId, sizeId, width, height} (width and height are the full size)
• 400 invalid_input: an unknown template or size, or copy over its limits
• 403 the studio is off
• 429 rate_limited (retry-after)

POST /v1/creative/assets/render

Render a brand-kit template (social-card, og-image, ad-image) at channel sizes — Satori + resvg + sharp, no AI. Each image is C2PA-signed and stored as a draft asset (governed tool creative.renderTemplate)

Scope: execute.

Responses

• 201 assets
• 400 invalid template, size or copy
• 403 read-only key or studio off
• 423 creative kill switch engaged
• 503 asset storage or C2PA signing not configured

POST /v1/creative/assets/generate

Generate one image with an allowlisted model (vertex:gemini-3-pro-image, vertex:gemini-3.1-flash-image, openai:gpt-image-2) within the monthly budget; the brief is screened for injection; the image is C2PA-signed as AI-generated (governed tool creative.generateImage)

Scope: execute.

Responses

• 201 asset
• 400 model not allowed or invalid input
• 402 monthly generation budget exceeded
• 422 prompt blocked or provider refused
• 423 creative kill switch engaged
• 503 provider, storage or signing not configured

POST /v1/creative/briefs/{actionId}/assets

Turn a staged creative brief (daily-creative-drop, playbook T-04/T-05) into draft assets: mode template | generate, itemIds?, model?, sizeId?, format?

Scope: execute.

Parameters

Responses

• 201 assets
• 207 some assets made before a refusal
• 400 no creative brief, no matching items, or invalid body
• 404 not found

POST /v1/creative/remotion-spec

W5-D3: compile a release's grounded facts (a W5-D2 release launch run's, by factoryRunId, or release notes given here) and the Brand Kit into a validated Remotion composition spec (ProductLaunchChangelogV1: hook, feature bullets, at most one metric proof, call to action; 16:9 1920×1080, 9:16, 1:1; 30 fps) per aspect, under claim guardrails (every scene cites a release fact; a metric proof's metric, every number and any superlative must be stated by the facts it cites; links only to the release's pages), and sign each spec's storyboard as a draft asset whose C2PA manifest binds the spec's SHA-256 (com.heycmo.composition). HeyCMO renders no video: render the spec with your own Remotion project. Governed tool creative.composeLaunchVideo

Scope: execute.

Request body (application/json, required)

Responses

• 200 {release, compositions: [{aspect, specSha256, spec, remotion, captionsSrt, storyboard: null}], notes, rendered: false} (dry run, or storyboard: false)
• 201 {release, compositions: [{aspect, specSha256, spec, remotion, captionsSrt, storyboard, provenance}], notes, rendered: false}
• 400 invalid body: exactly one of factoryRunId and release; a release url that is not its repo's page for its tag
• 403 read-only key or studio off
• 404 no such run or studio asset
• 409 not a release launch run, no release facts, or a studio asset that does not verify
• 422 release notes a launch cannot cite (a draft, a pre-release, empty)
• 423 creative kill switch engaged
• 503 asset storage or C2PA signing not configured

GET /v1/creative/remotion-spec/{assetId}

W5-D3: a launch video storyboard's composition spec, re-verified: the stored bytes, the C2PA manifest and signer, and the spec's SHA-256 against the one the manifest signed. What a renderer fetches; nothing whose spec does not verify may be rendered

Scope: read.

Parameters

Responses

• 200 {aspect, specSha256, spec, remotion, captionsSrt, storyboard, provenance, rendered: false}
• 404 not found, or not a launch video storyboard
• 409 the storyboard or its spec no longer verifies (tampered, manifest or spec mismatch, untrusted signer)
• 503 asset storage could not be read

GET /v1/creative/canva

Canva brand templates (W3-5): the workspace's Canva connection (offered when the operator configured the Canva integration; status, readiness, missing scopes) and the latest renders

Scope: read.

Responses

• 200 {connection, renders}

GET /v1/creative/canva/templates

The connected Canva user's brand templates that have autofill fields, newest first, and whether the Canva plan has Autofill (governed tool creative.listCanvaTemplates)

Scope: read.

Parameters

Responses

• 200 {templates, continuation, capabilities}
• 403 studio off, or the Canva plan lacks brand templates
• 409 Canva not offered or not connected
• 423 creative kill switch engaged
• 429 Canva's rate limit
• 502 Canva unavailable

GET /v1/creative/canva/templates/{templateId}

One brand template's autofill fields (name, type text|image|chart|sheet) and the mapping each uses: the workspace's own, or the default by name and type (governed tool creative.readCanvaTemplate)

Scope: read.

Parameters

Responses

• 200 {template, fields, stale}
• 404 not found
• 409 Canva not offered or not connected
• 423 creative kill switch engaged

PUT /v1/creative/canva/templates/{templateId}/mapping

Set the workspace's field mapping for one Canva brand template (admin): {fields: {<field name>: {source: headline|body|cta|eyebrow|objective|angle|brandName|none} | {source: 'text', text} | {source: 'asset', assetId?}}}, checked against the template's current fields; {} goes back to the defaults. Audited

Scope: admin.

Parameters

Request body (application/json, required)

Responses

• 200 {ok, template, fields, stale}
• 400 malformed mapping, unknown field, or a source that cannot fill the field
• 403 read-only key or not admin
• 409 a studio asset that is not signed, or Canva not connected

POST /v1/creative/canva/renders

Autofill a Canva brand template from a staged creative brief (briefActionId, briefItemId?) or copy, with the workspace's signed studio images for image fields, export it (png | jpg) and sign the export into a draft asset (Canva's export as the c2pa.opened parent; AI-generated when an AI image was placed). Starts a run (202) that finishes in the background; dryRun: true answers the fill plan and writes nothing to Canva (governed tool creative.renderCanvaTemplate)

Scope: execute.

Request body (application/json, required)

Responses

• 200 {plan} (dry run)
• 202 {render} started
• 400 invalid body, or nothing to fill
• 403 read-only key, studio off, or the Canva plan lacks Autofill
• 409 Canva not connected, or a studio image that is not signed
• 423 creative kill switch engaged
• 429 three renders already running, or Canva's rate limit

GET /v1/creative/canva/renders/{id}

One Canva render: running | succeeded (the design id and the signed asset with a short-lived URL) | failed (a closed error code); a run interrupted by a restart reads as failed

Scope: read.

Parameters

Responses

• 200 {render}
• 404 not found

POST /v1/decline/{id}

Decline staged action (reject_action)

Scope: approve.

Parameters

Responses

• 200 declined

POST /v1/deliverability/dmarc-reports

Ingest one DMARC aggregate (RUA) report (E3.8): the raw gzip or zip attachment, or the XML. Size-capped, no DTDs or entities; a re-delivered report is a no-op

Scope: execute.

Request body (application/gzip)

string (binary)

Responses

• 200 duplicate (already stored)
• 201 stored {reportId, orgName, domain, records, messages, passRate}
• 413 too large
• 415 not gzip, zip or XML
• 422 malformed, or a DTD/entity declaration

GET /v1/deliverability

Measured DKIM / SPF / DMARC status for the sending domain: DMARC pass rates by source (30 days of reports) and Gmail Postmaster Tools v2 when connected; not_measured otherwise (E3.8)

Scope: read.

Responses

• 200 {domain, statuses, sources, dmarc, postmaster}

GET /v1/esp/metrics

Live per-message and per-day email metrics from the connected ESP(s), through governed reads (aggregates only, no people)

Scope: read.

Parameters

Responses

• 200 {stats: [...], failures: [...]}
• 404 no ESP connected

GET /v1/esp/customerio/audience

Customer.io API-triggered broadcasts and segment ids/names (never members)

Scope: read.

Responses

• 200 {region, broadcasts, segments}

POST /v1/esp/customerio/broadcast-triggers

Stage a Tier-2 customerio.triggerBroadcast to an existing segment, with the broadcast email snapshotted for approval and the approver's consent attestation; nothing is sent here

Scope: execute.

Request body (application/json)

Responses

• 201 {stagedActionId, preview, posture, …}
• 400 invalid body or the operation was refused (attestation, person-level fields)
• 404 broadcast or segment not found, or no Customer.io connected
• 422 the broadcast must have exactly one email message with a sender

GET /v1/experiments

The tenant's experiments (E2.3 randomized holdouts) and the holdout consent text. #236: each experiment carries sourceActionId (the approved experiment_brief a draft came from, or null) and stopNotice (a met stopping rule the daily pass recorded: metAt, reason, notifiedAt, undeliveredAt, undeliveredReason; or null)

Scope: read.

Responses

• 200 {experiments: [{…, sourceActionId, stopNotice}], supportedLoops, consent}

POST /v1/experiments

Draft a holdout experiment (admin): failed-payment-dunning (unit invoice), re-engagement or trial-conversion (unit Stripe customer, E3.10); defaults to a 10% control

Scope: admin.

Request body (application/json)

Responses

• 201 {experiment, consent}
• 400 invalid input or loop not wired
• 409 key already used

POST /v1/experiments/{id}/start

Start a drafted holdout (admin). Needs the acknowledged consent: held-out units get no action

Scope: admin.

Parameters

Request body (application/json)

Responses

• 200 running
• 400 consent not acknowledged (the body carries the terms)
• 404 not this tenant’s experiment
• 409 not a draft, or another experiment runs for the loop

POST /v1/experiments/{id}/stop

Stop enrolment (admin); held-out units stay out until their window ends. conclude:true freezes the result once nothing is pending

Scope: admin.

Parameters

Request body (application/json)

Responses

• 200 {experiment, pendingUnits, note?}
• 404 not this tenant’s experiment
• 409 not stoppable, or units still pending for conclude

GET /v1/experiments/{id}/results

Per-arm counts and outcome rates, lift with an always-valid 95% interval (and the posterior one), P(treatment > control), z-test, sequential power and the readiness caveat; the post-stratified lift, recovered money per enrolled unit by currency, and the partially pooled lift for the current holdout. W5-C1: every comparison (the rate and each currency) carries eValue and alwaysValidPValue (mixture SPRT, replayed over every window end, sequentialTest says how), and offPolicy has doubly robust values of treating every unit, none, or only where a model expects a lift, from the logged assignment propensities (directional; null when it cannot be estimated). unitReads says whether the units were read one by one (at most 100,000 assignments, in pages; past that the read is its counts alone). A read: it never records a met stopping rule (the daily pass does)

Scope: read.

Parameters

Responses

• 200 {experiment, scope: tenant, analysis, pendingUnits}
• 404 not this tenant’s experiment

GET /v1/external-writes

External-write adapters and the tenant's recent append-only attempt ledger

Scope: read.

Responses

• 200 {adapters, attempts}

POST /v1/external-writes

Stage an external write (E4.0) for human approval: validated by its adapter, stored as the canonical operation the approval binds. Sends nothing

Scope: execute.

Request body (application/json)

Responses

• 200 the identical operation was already staged today
• 201 {stagedActionId, actionType, channels, target, preview, estimateSpendCents, posture}
• 400 the adapter refused the operation or its preview
• 404 no external-write adapter for actionType
• 409 a creative asset is refused (asset_unverified), a reversal was posted here (reversal_requires_request), or the adapter's staging check refused the write (staging_refused, with its reason, e.g. political_authorization_missing)

POST /v1/external-writes/cms-drafts

Send to CMS as draft (E3.5): stage one cms.publishPost draft built from a T-01 blog-post, T-02 page-copy or T-08 press-release draft. Sends nothing. An SEO content brief (either kind) or a GEO report is drafted with "Draft this" (POST /v1/content/drafts) instead (#233)

Scope: execute.

Request body (application/json)

Responses

• 200 this source was already sent to that CMS
• 201 {stagedActionId, actionType, channels, target, preview, posture, source}
• 404 source action not found
• 409 no (or no single) CMS connected
• 422 not_cms_draftable — the source is not a T-01, T-02 or T-08 draft; an SEO content brief or a GEO report answers: use "Draft this" (POST /v1/content/drafts), which writes the article from the brief — a new page, or the changes to the page that already ranks

POST /v1/external-writes/landing-page-variants

W2-8: stage one cms.publishPost draft page per "## Variant <label>" section of a PB-12 landing-page draft (slug <page>-<label>, variant {of, label}) in a CMS that keeps landing pages (Sanity, Contentful, Git). Sends nothing; each page is its own approval

Scope: execute.

Request body (application/json)

Responses

• 200 every variant was already staged
• 201 {sourceActionId, platform, target, variants: [{label, slug, stagedActionId, alreadyStaged}], channels, posture}
• 404 source action not found
• 409 no (or no single) connection that keeps landing pages
• 422 the source is not a PB-12 landing-page draft, or it has no variant sections

POST /v1/external-writes/linkedin-drafts

Send to LinkedIn (E4.2): stage one LinkedIn post draft (text + link card, or text + a C2PA-signed creative asset as its image) from a content-repurposing report or a live published CMS post — a linkedin.publishPost by the Page, or (W2-2) a linkedin.publishMemberPost by the founder's own profile. W4-B3: the text is written in voice by the model and checked (never a template); its payload carries the voice record. Sends nothing

Scope: execute.

Request body (application/json)

Responses

• 200 this page was already sent to LinkedIn from this source
• 201 {stagedActionId, actionType, channels, target, preview, posture, sourceActionId, url}
• 404 source action or creative asset not found
• 409 LinkedIn not connected, no Page (or own profile, for author member) chosen, or the creative asset is not signed / fails verification; W4-B3: the voiced drafter refused ({code: no_model|model_off|budget|blocked_input|checks_failed|judge_failed|model_error, error} in plain words), nothing staged
• 422 the source is not a content-repurposing report or a live CMS post

POST /v1/external-writes/x-drafts

Send to X (W2-2): stage one x.publishPost draft (W4-B3: written in voice by the model and checked, with the page's link, within X's weighted 280; never a template; its payload carries the voice record) for the connected X account from a content-repurposing report or a live published CMS post. Sends nothing; once approved, X bills the post ($0.20 with a link) and the spend caps are checked before it is sent

Scope: execute.

Request body (application/json)

Responses

• 200 this page was already sent to X from this source
• 201 {stagedActionId, actionType, channels, target, preview, estimateSpendCents, posture, sourceActionId, url}
• 404 source action not found
• 409 X not connected, or its account not recorded yet; W4-B3: the voiced drafter refused ({code: no_model|model_off|budget|blocked_input|checks_failed|judge_failed|model_error, error} in plain words), nothing staged
• 422 the source is not a content-repurposing report or a live CMS post

GET /v1/external-writes/ad-campaigns

Propose an ad change (C3): the campaigns a change can name, per connected network (Google Ads, Microsoft Advertising), read live — status, daily budget, own or shared budget, bidding strategy, the actions each can take and, for Google Ads, the ad groups whose bid a change may set. A network that cannot be read is listed as unavailable with why; nothing is invented. At most 500 campaigns a network are listed (Google Ads: lowest ids first); truncated says the account has more, and POST /v1/external-writes/ad-changes takes any campaign id, listed or not

Scope: read.

Responses

• 200 {networks: [{network, name, target, currencyCode, campaigns: [{campaignId, name, status, dailyBudgetMicros, biddingStrategyType, actions: [pause|enable|budget|bid], budgetNote?, adGroups?: [{adGroupId, name, bid: cpc|target_cpa, bidMicros}]}], truncated}], unavailable: [{network, name, reason}]}

POST /v1/external-writes/ad-changes

Propose an ad change (C3): stage a pause, a turn-on, a daily budget change or (Google Ads) an ad group bid change as the same Tier-2 card the ad-fatigue producers would — the named campaign read live on its own (listed by GET /v1/external-writes/ad-campaigns or not), the same payload, the same staging as POST /v1/external-writes. Sends nothing; a person approves it in the inbox. A budget or bid change is bounded to ±30% per approval

Scope: execute.

Request body (application/json)

Responses

• 200 the same change is already staged today (the same card)
• 201 {stagedActionId, actionType, channels, target, preview, estimateSpendCents, capRefusal, network, action, pacing: {headline, status, fits, note}|null, posture}
• 400 invalid body, or the adapter refuses the change (code invalid_operation, e.g. beyond ±30%)
• 403 read-only key
• 404 campaign_not_found or ad_group_not_found in the connected account
• 409 not_connected, unreadable (connected, but its campaigns could not be read just now), nothing_to_change (already paused…) or shared_budget

GET /v1/external-writes/applied

Recent external writes the provider accepted live, each with whether a person can reverse it now (and why not)

Scope: read.

Parameters

Responses

• 200 {writes: [{id, actionType, provider, channels, target, title, executedAt, externalRef, reverses, reversal, outcome: {metricId, why, page?: {url, isNew}, readbacks: [{metricId, windowDays, changeDay, readiness, outcome, label, beforeMean, afterMean, difference, relativeChange, trust, causal: false, note, page: {url, isNew, clicks: {before, after}, impressions: {before, after}, position: {before, after}} | null}]}}], more} — more: older applied writes exist past this page; #235 outcome: the metric the write is meant to move and its recorded 14- and 28-day readbacks (directional, never causal); #233: a CMS write that changed a live page targets that page (page), read back on it in Search Console at 14, 28 and 56 days, and a draft save targets nothing

POST /v1/external-writes/{actionId}/reverse

Request the reversal of one applied external write: stages a Tier-2 <actionType>.reversal item bound to exactly that write (its staged action, approved operation hash, operation digest and provider ref). Sends nothing; a person approves it in the inbox

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 the same reversal was already staged (a concurrent request)
• 201 {stagedActionId, actionType, channels, target, preview, estimateSpendCents, reverses, compensation, posture}
• 404 no write with this id in this workspace
• 409 not applied, a reversal is pending, or the write was already reversed (code, reversalActionId)
• 422 not reversible: the adapter cannot undo it, it was rehearsed, it is itself a reversal, or undoing it would not restore what was there before

GET /v1/factory/runs

List this workspace’s campaigns, newest first (read scope)

Scope: read.

Parameters

Responses

• 200 {items: FactoryRunRecord[], count}

POST /v1/factory/runs

Plan and draft a campaign from a marketing goal (execute scope)

Reads tenant context. Missing audience, message or destination holds the plan for correction. checkpointBlueprint requests plan review before drafting; MCP always requests it. Drafts stage in the approval inbox and never publish directly.

Scope: execute.

Request body (application/json, required)

Responses

• 201 FactoryRunRecord: blueprint, drafts, checks, approval state and generation provenance
• 400 Missing goal or invalid measurement
• 403 execute scope required

GET /v1/factory/runs/{runId}

Read this workspace’s campaign and current edited copy and delivery state (read scope)

Scope: read.

Parameters

Responses

• 200 FactoryRunRecord, hydrated from current staged actions
• 404 Campaign not found in this workspace

POST /v1/factory/runs/{runId}/resume

Correct or accept a campaign plan, or finish reviewing its drafts (approve scope)

Plan acceptance drafts into the inbox. decision=approve_all requires a person where dashboard identity is configured; a machine caller receives an approveUrl. approve_all names, in operationHashes, the operation hash of each draft as shown (stagedActions[].operationHash on the run read): if any waiting draft is missing or has changed since, nothing is approved (409). complete requires all staged items to have been reviewed. Invalid or concurrent transitions return 409. MCP exposes only plan correction/acceptance.

Scope: approve.

Parameters

Request body (application/json, required)

Responses

• 200 Updated FactoryRunRecord
• 400 Invalid input or missing campaign context
• 403 approve scope or human_approval_required with approveUrl
• 404 Campaign not found
• 409 Campaign is not at the requested review step, still has unreviewed drafts, or (approve_all) a draft changed since it was shown; nothing is approved

GET /v1/factory/runs/{runId}/results

Read campaign delivery counts and its selected workspace metric (read scope)

Returns published, reviewedDrafts, pending, failed, unknown, rehearsed and declined counts. Measurement includes the observation’s source and trust; targetMet stays null until a due target has a trusted observation collected since this campaign began. Workspace metrics are not campaign attribution or causal lift.

Scope: read.

Parameters

Responses

• 200 FactoryResults {delivery, measurement}
• 404 Campaign not found

POST /v1/factory/runs/{runId}/results

Record a sourced result review for future planning (execute scope)

Scope: execute.

Parameters

Responses

• 200 FactoryResults; evidence saved with causal:false and an audit record
• 400 A due goal and a trusted observation collected since the campaign began are required
• 403 execute scope required
• 404 Campaign not found

GET /v1/factory/prompt-specs

W5-B1 (#277): the prompt optimizer's compiled channel prompt specs: for each channel (linkedin, x, cms, email, ads, landing) its dataset cases (founder edits and text declines of the last 180 days), its active spec (the rules learned from those edits, the phrases to avoid, the few-shot cases by id, its validation score against the spec it replaced) and every version kept (active, superseded, rolled_back)

Scope: read.

Parameters

Responses

• 200 {enabled, channels: [{channel, cases, active: {version, status, rules: [{feature, text, support, addedInVersion, maxChars?}], bannedPhrases, fewShotCases: [{caseId, actionType, editDistanceRatio}], baselineScore, candidateScore, caseCount, gradientSource: rules|model, parentVersion, compiledAt, statusChangedAt} | null, versions: [same, newest first]}]}
• 400 unknown channel

POST /v1/factory/prompt-specs/compile

W5-B1: compile a channel's prompt spec now (the same compile every third new founder edit or decline starts): the backward critique of its cases, the candidate instructions scored leave-one-out by the founder-edit alignment scorer and the factory scorer suite, and promotion of a new version only when the best candidate scores strictly above the active spec; audited either way

Scope: execute.

Request body (application/json)

Responses

• 200 {channel, joined (true: a compile of this channel was already running in this API task, automatic or on demand; this is its result), trigger (auto|manual: the compile reported), promoted, version, reason, caseCount, baselineVersion, baselineScore, best: {id, score}, candidates: [{id, label, score, alignment, suite, newRules, newPhrases}], gradient: {source, violatedRule, proposedInstructionDelta, bannedPhraseAdditions, spanCritiques}, modelNote, fewShotCases, spec? (when promoted)}
• 400 body must name a channel
• 403 read-only key
• 409 the prompt optimizer is off (HEYCMO_PROMPT_OPTIMIZER=off)

POST /v1/factory/prompt-specs/rollback

W5-B1: roll a channel's prompt spec back: the active version becomes rolled_back and the version before it (or toVersion; none = HeyCMO's base prompt) becomes active. Nothing is deleted; a rolled-back rule comes back only on edits newer than the rollback. Audited

Scope: execute.

Request body (application/json)

Responses

• 200 {ok: true, channel, from, to} (to: null = the base prompt)
• 400 invalid channel or toVersion
• 403 read-only key
• 404 unknown_version
• 409 no_active: no active spec to roll back

GET /v1/factory/prompt-specs/quality

C5 (#369): how the workspace's drafts fared by loop, action type and the prompt-spec version they were drafted with (null: none), over the cards staged in the last days (default 90): cards staged, approved, declined and edited by a person, the decline rate, and each scorer's mean score (the Factory's checks and the live judge's sampled grades). Ids and numbers only

Scope: read.

Parameters

Responses

• 200 {days, rows: [{loop, actionType, promptSpecVersion, staged, approved, declined, edited, declineRate (null before any decision), scores: {<scorer id>: {mean, count}}}]}
• 400 days not a whole number from 1 to 730, or loop too long

GET /v1/founder-post

C6 (#237): the founder-post loop's cadence (posts a week, days, networks; stored: false while the defaults are in effect) and "What will post this week": each planned post with its day, network, topic, status, the first words of the post and its 48-hour numbers (or why there are none)

Scope: read.

Responses

• 200 {loopId, settings: {postsPerWeek, days, networks, stored, updatedAt}, week: {weekStart, settings, destinations, posts: [{slot, day, date, network, candidateKind, topic, status: waiting|approved|posted|rehearsed|declined|failed|not_staged, stagedActionId, actionType, note, excerpt, readback}]}}

PUT /v1/founder-post

Set the founder-post cadence (admin, audited): postsPerWeek (1–7), days (mon…sun), networks (linkedin|x|facebook; empty = every connected one); only the keys sent change

Scope: admin.

Request body (application/json)

Responses

• 200 {ok, loopId, settings, week} (as GET)
• 403 read-only key or no admin scope
• 422 invalid_settings with issues [{path, message}]

GET /v1/geo

GEO visibility (E3.4): engine status, the LLM Mentions baseline status, the prompt set, cadence, the newest complete panel (share of voice, citation share, gaps, week-over-week movement, guarded recommendations, metric ids, the mentions baseline; W5-C3: mean PAWC, attributed word share and cited-domain entropy, drifted answers and the drift list, absent on a panel summarized before them, and driftGrounded: whether the price and capability rules of the drift check ran against the product context), the trend (with pawc and driftAnswers per panel), a panel in progress, the Search Console exports on file and the settings (the newest panel is read under the current Google AI exclusion)

Scope: read.

Responses

• 200 {engines, mentionsSource, loop, cadence, promptSet, latest (design v2: with gapFixes, each citation gap's fix by prompt id: {briefActionId, briefStatus, query, draftActionId, draftStatus, draftRehearsed}, from the newest GEO page brief of the last 120 days that lists it and the page drafted from it), trend, inProgress, policy, searchConsoleExport, settings}

GET /v1/geo/settings

The tenant's GEO settings: whether its site is excluded from Google's AI features in Search Console

Scope: read.

Responses

• 200 {settings: {excludedFromGoogleAi}}

PUT /v1/geo/settings

Say whether the site is excluded from Google's AI features in Search Console (admin; no API reports it). When it is, AI Overview and AI Mode answers are not counted as citation gaps and get no recommendation

Scope: admin.

Request body (application/json)

Responses

• 200 {settings}
• 400 invalid input

GET /v1/geo/runs/{id}

One GEO panel run's answers with their analysis (W5-C3: pawcScore, attributedWordShare, domainEntropy, citationDriftDetected and citationDrift findings per answer, null on an answer stored before them); answer excerpts are third-party text

Scope: read.

Parameters

Responses

• 200 {run, summary, metricIds, results}
• 404 not this tenant's run

GET /v1/geo/prompt-sets

The GEO prompt set's versions (every save is a new immutable version)

Scope: read.

Responses

• 200 {versions}

GET /v1/geo/prompt-sets/{version}

One GEO prompt-set version

Scope: read.

Parameters

Responses

• 200 {promptSet}
• 404 no such version

PUT /v1/geo/prompt-set

Save a new GEO prompt-set version (admin). A daily cadence needs the paid add-on

Scope: admin.

Request body (application/json)

Responses

• 200 {promptSet}
• 400 invalid input
• 402 daily cadence without the add-on

POST /v1/geo/prompt-set/seed

Propose a GEO prompt set from Search Console queries (or an uploaded Queries export) and the product context (admin); saved unless save is false

Scope: admin.

Responses

• 200 {draft, notes} (save: false)
• 201 {promptSet, notes}
• 422 nothing to seed from

POST /v1/geo/gaps/{promptId}/plan

Design v2 AI answers, "Plan this fix" (execute): a page brief (seo_content_brief, kind new_page, source geo) for one citation gap of the newest complete panel, enriched like the weekly check's and put on the editorial calendar; a question that already has a brief gets it back

Scope: execute.

Parameters

Responses

• 200 {briefActionId, alreadyStaged: true, query}: the question already has a brief
• 201 {briefActionId, alreadyStaged: false, query}
• 403 read-only key
• 404 not_a_gap: no such question, or no assistant links a competitor and not you for it in the newest panel
• 409 no_panel: no AI answers check has finished yet

PUT /v1/geo/search-console-export

Upload one Search Console table export (execute): the Performance report's Queries table (seeds prompts without a Search Console connection) or the Generative AI report's Dates table (Google's own AI Overview / AI Mode impressions); replaces the earlier upload of that report

Scope: execute.

Request body (text/csv)

string (up to 262144 characters)

Responses

• 201 {export: {report, uploadedAt, rows, from, to, totalImpressions}}
• 413 over 256 KB or 1,000 rows
• 415 not one of the two accepted Search Console tables
• 422 a row that does not parse (row number and column named)

GET /v1/governor/policy

A2: the caps the governor enforces now — sendPerDay (sendPerRun is a deprecated read alias of the same value), changePerRun, massAudienceThreshold, the usd spend caps, spend caps per other currency, the model-spend limit and the always-escalate list

Scope: read.

Responses

• 200 {tenantId, plan, caps: {sendPerDay, sendPerRun, changePerRun, massAudienceThreshold, spendDailyCents, spendWeeklyCents}, spendCapsByCurrency, llm: {dailyCents, weeklyCents, dailySource, weeklySource}, alwaysEscalate}

GET /v1/inbox

Approval inbox (list_pending_actions)

Scope: read.

Parameters

Responses

• 200 inbox items + capStatus
• 400 Invalid status or actionId
• 401 auth

GET /v1/inbox/track-record

Decisions people made per loop and action type (approved, declined, edited) over the last days days — the inbox card's track record

Scope: read.

Parameters

Responses

• 200 {windowDays, records: [{loop, actionType, decided, approved, declined, edited, editedApproved, outcomes: {byWindow: [{windowDays, readbacks, improved, declined, flat, increased, decreased, notReadable, newPages}], direction, latest: [{stagedActionId, metricId, windowDays, changeDay, readiness, outcome, label, beforeMean, afterMean, difference, relativeChange, trust, page}], causal: false, note} | null}], definition} — #235 outcomes: the 14- and 28-day readbacks of the metric each applied write is meant to move, directional, never causal; outcome improved | declined (by the metric's good direction), increased | decreased (a metric with none: never better or worse), flat (barely moved); #233: readbacks of a published or edited page on that page (14, 28 and 56 days; page gives its Search Console clicks, impressions and position; newPages counts new pages, which have no before); C6 (#237): posts — {read, impressions, engagements, notExposed, rehearsals, unavailable, latest} for social posts read back 48 hours after publishing; coverage — {sent, quoted, latest: [{outcome, outlet, url, markedAt}]} on the journalist desk's fact sheets' record

PUT /v1/ingest/{kind}

Partner sense ingest (tracking|activity|ads|…)

Scope: execute.

Parameters

Responses

• 200 snapshot upserted

GET /v1/journalist-desk

Journalist desk (#173): the address to forward HARO, Featured, Qwoted, Source of Sources and MentionMatch digests to, forwarding settings, the Gmail forwarding confirmation code while set-up is pending, the last message's outcome, the services, what requests are matched against, and stored requests with deadlines, matches and fact sheets: the open ones soonest deadline first (requests, up to 100, with openCount), then the latest past their deadline (closed, up to 20, with closedCount)

Scope: read.

Responses

• 200 address, loop, settings, forwardingConfirmation, lastMessage, services, expertise, retention, requests (each with body (at most 1,200 characters) and requirements, the lists of its fact sheet, factSheet: {actionId, status, facts, numbers, talkingPoints, howToAnswer} | null, and coverage: {outcome, url, markedAt} | null, C6; design v2 Press: skippedAt, when it was set aside, and sheetEmailedAt, when the caller last emailed themselves its fact sheet, each an ISO time or null), openCount, skippedCount (the open requests set aside, still listed), closed, closedCount, coverage: {windowDays, sent, quoted, latest: [{id, outcome, outlet, url, service, markedAt, requestListed}]} (C6; a tick whose request was deleted is changed at PUT /v1/journalist-desk/coverage/{id})

PUT /v1/journalist-desk

Set journalist desk settings (admin): forwardingSenders (addresses or company domains the tenant forwards from), topics

Scope: admin.

Responses

• 200 updated
• 400 invalid or unknown field

PUT /v1/journalist-desk/requests/{id}/coverage

C6 (#237): the "sent / quoted / link" tick on a journalist request: what came of answering it (null clears it). Kept by the request's service and key, so it outlives the request and feeds the track record (coverage). Audited

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 {ok, coverage: {outcome, url, markedAt} | null}
• 400 invalid body
• 403 read-only key
• 404 no such request

PUT /v1/journalist-desk/requests/{id}/skip

Design v2 Press: "Skip this request". Sets the request aside (it stays listed; the journalist-desk loop prepares no fact sheet for it, and a fact sheet already waiting stays in the Inbox) or, with skipped: false, brings it back (Undo). Audited when it changes

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 {ok, skippedAt: ISO time | null}
• 400 invalid body
• 403 read-only key
• 404 no such request

POST /v1/journalist-desk/requests/{id}/email

Design v2 Press: "Email me the fact sheet". Emails the request's fact sheet from the platform sender to the signed-in person's own address (the verified session token's email claim, else the one their account kept) and nobody else. Only a person signed in to the dashboard (a Clerk or AuthKit session), at most 10 an hour each; audited without the address. Nothing is ever sent to a journalist

Scope: execute.

Parameters

Responses

• 200 {ok, sentTo: the address it went to, emailedAt}
• 403 a key, an MCP client or the CLI (code person_required), or a read-only session
• 404 no such request
• 409 no fact sheet yet (code no_fact_sheet), or the sign-in has no email address (code no_email)
• 429 ten this hour already (code rate_limited)
• 502 the email could not be sent (code email_failed)
• 503 platform email is not set up on this deployment (code email_unconfigured)

PUT /v1/journalist-desk/coverage/{id}

C6 (#237): the same "sent / quoted / link" tick changed by its own id (GET /v1/journalist-desk coverage.latest[].id): the piece often appears after its request was deleted (a week after its deadline). Null clears it. Audited

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 {ok, coverage: {outcome, url, markedAt} | null}
• 400 invalid body
• 403 read-only key
• 404 no such tick

GET /v1/journalist-desk/podcast-cards/{id}

A podcast guest card (podcast_guest_fact_sheet) as it is shown. One Listen Notes found keeps only the episode's id and publication date (Listen Notes' API terms for FREE and PRO allow storing nothing else), so the show, the episode, what was said and when, why it matched and the fact sheet are read from Listen Notes again now, by sending the search word that found it again, narrowed to that episode: one request against the workspace's monthly Listen Notes budget, under the listening kill switch, returned with "Powered by Listen Notes" and never stored (cache-control: private, no-store). A Podscan or Podcast Index card comes back as stored, with no request

Scope: read.

Parameters

Responses

• 200 {id, status, operationVersion, live, card}: card is the payload as shown; with live, its live.read says whether Listen Notes was read now, and live.note why not
• 404 not this workspace's podcast guest card

GET /v1/killswitch

Kill switch status: tenant switch, tenant channel stops, engaged platform stops, env ceilings

Scope: read.

Responses

• 200 {killSwitch, channels, platform:{global,channels,tools}, engaged, ceilings}
• 503 switch state unreadable (execution refuses fail-closed)

POST /v1/killswitch

Engage (execute|admin) / release (admin; where people sign in, a signed-in person only) the tenant-wide kill switch

Scope: execute or admin to turn it on, admin to turn it off, and wherever people sign in only a signed-in person turns it off.

Responses

• 200 updated
• 403 scope, or person_required (a key, an OAuth client or the CLI releasing where people sign in)

POST /v1/killswitch/channels/{channel}

Engage (execute|admin) / release (admin; where people sign in, a signed-in person only) one tenant channel stop

Scope: execute or admin to turn it on, admin to turn it off, and wherever people sign in only a signed-in person turns it off.

Parameters

Request body (application/json)

Responses

• 200 updated
• 400 bad channel/body
• 403 scope, or person_required (a key, an OAuth client or the CLI releasing where people sign in)

GET /v1/landing-pages

Hosted landing-page variant tests (W3-7): whether the variant host is set up on this deployment (and its CNAME target), the landing-pages write posture, the tenant's hostnames with the DNS records to add, its tests, landing-page drafts with ## Variant sections, publish and stop cards waiting in the inbox, the terms an approver accepts, and the plan's defaults and bounds

Scope: read.

Responses

• 200 {host, posture, hostnames, tests, drafts, pending, terms, defaults, bounds, goalKinds, stripeGoalWindows}

POST /v1/landing-pages/hostnames

Claim a hostname you own (a subdomain such as try.example.com) for hosted landing-page tests (admin; audited; a paid plan or Alpha). Nothing reaches the host yet: answers the DNS records to add — the _heycmo-challenge TXT record that proves this workspace controls the hostname, and the CNAME to the CNAME target

Scope: admin.

Request body (application/json)

Responses

• 201 {hostname: {id, hostname, status: pending|active|failed, sslStatus, dnsRecords, lastError, ownershipVerifiedAt, verifiedAt}}
• 400 invalid_hostname (an apex domain, a URL, a reserved or HeyCMO name)
• 402 plan_entitlement: a no-card trial, no plan, or a restricted workspace
• 409 hostname_connected, hostname_taken (another workspace holds it verified), hostname_limit, or variant_host_unconfigured
• 423 a kill switch stops the landing-pages channel

POST /v1/landing-pages/hostnames/{id}/check

Check a hostname (admin; at most once a minute): first the _heycmo-challenge TXT record (proof of control, which takes the hostname over from other workspaces' unproven claims), then the host; active once the host reports the hostname and its certificate active. A hostname the host no longer has turns failed and is registered again on the next check

Scope: admin.

Parameters

Responses

• 200 {hostname}; lastError awaiting_ownership while the TXT record is missing
• 404 not this tenant's hostname
• 409 hostname_taken, variant_host_unconfigured or not_ready
• 429 check_cooldown (retryAfterSeconds), or the host is rate limiting
• 502 the host refused (closed code)
• 503 dns_unavailable, or the host is unavailable or its hostname quota is used up

DELETE /v1/landing-pages/hostnames/{id}

Remove a hostname and its certificate at the host (admin; audited); refused while a test is served on it, except in a restricted workspace, whose test is taken down with it. Answers the DNS records the customer should now delete

Scope: admin.

Parameters

Responses

• 200 {removed, id, testsTakenDown, dnsCleanup: {message, records}}
• 404 not this tenant's hostname
• 409 hostname_in_use

POST /v1/landing-pages/tests

Stage the publish of a landing-page draft (PB-12, 2–4 ## Variant sections) as a hosted test on a verified hostname: one Tier-2 landingpages.publishVariants card with every variant, the split, the conversion goal (default: the first https link of the control) and the plan. Nothing is published until a person approves it. #235: goalKind trial_started or first_paid_invoice counts a live Stripe trial or first paid invoice of a visitor who followed a goal link (joined through the hc_ref the link carries to the site; measurement window 14 or 45 days by default, at most 30 or 60) instead of the click

Scope: execute.

Request body (application/json)

Responses

• 200 the same card was already staged today
• 201 {stagedActionId, alreadyStaged, actionType, channels, target, preview, sourceActionId, hostname, variants, goalUrl, goalKind, posture}
• 400 invalid input, or the operation refused (invalid_operation)
• 404 source or hostname not found
• 409 hostname_not_verified
• 422 not_landing_page, source_declined, no_variants, too_many_variants, no_goal

GET /v1/landing-pages/tests/{id}/results

A hosted test's read-out with the holdout statistics (#164): per variant visitors, measured visitors and conversions, the rate with its interval; each variant against the control with the always-valid interval (Bonferroni across comparisons), its always-valid p-value and e-value (W5-C1, replayed visitor by visitor up to 100,000 measured visitors, unitReads says which; null while not_enough_data), power and the label not_enough_data | leaning | decided | no_clear_winner

Scope: read.

Parameters

Responses

• 200 {test, experiment, generatedAt, enrollment, readout: {verdict, headline, arms, comparisons, daysRunning, plannedDays, minDays, method}, winner (#236: the variant a decided read-out names, else null), promotion (#236: {label, at, unmeasured, serving} once an approved promotion concluded the test, with readout the one it froze; serving false after its undo), or null}
• 404 not this tenant's test

POST /v1/landing-pages/tests/{id}/stop

Stage the stop of a live hosted test: one Tier-2 landingpages.stopTest card. Once approved, new visitors see the control and are not measured; enrolled visitors keep their variant until their window ends

Scope: execute.

Parameters

Responses

• 201 {stagedActionId, alreadyStaged, preview, posture}
• 404 not this tenant's test
• 409 not_live

POST /v1/landing-pages/tests/{id}/promote

Stage the promotion of a decided hosted test's winner: one Tier-2 landingpages.promoteWinner card bound to the test, its version and the variant (default the read-out's winner). Once approved, every visitor sees that variant and the test is concluded with its read-out frozen; reversible (the control is served again)

Scope: execute.

Parameters

Request body (application/json)

Responses

• 201 {stagedActionId, alreadyStaged, preview, posture, testId, variant}
• 404 not this tenant's test
• 409 not_decided | not_winner | not_promotable (taken down, already promoted or concluded), in words

GET /v1/loop-specs

Tenant dynamic loop specs (loops-as-data Wave C)

Scope: read.

Responses

• 200 AI-authored specs with status

POST /v1/loop-specs/{loopId}/retire

Retire a dynamic loop spec (admin)

Scope: admin.

Parameters

Responses

• 200 retired
• 404 no such spec

GET /v1/loops

Loop catalog (list_loops)

Scope: read.

Responses

• 200 loops with runnable/enabled, enabledAt (when it was turned on; null while off, or on since before this was kept), cron and next scheduled run; B6: purpose, actsWhen and output (the catalog anatomy), requires ([{source, label, remedy}]: any one lets the loop sense; [] = its own records), alsoReads ([{source, label}]) and lastRun ({startedAt, finishedAt, outcome, firstRun, sensed, eligible, staged, actionable} | null) for every loop; B5: overrides[] {param, label, unit, from (the code default), to, appliedAt, inForce}, the settings an approved portfolio review tuned (a person's own saves are only in settings[]); design v2: settings[] {name, label, unit, role, default, value (in force), min, max, set: {at, by: person | review} | null}, every setting the loop registers

PUT /v1/loops/{id}/params

Design v2 Job detail, "Save settings" (admin): set some of a loop's registered settings, each a whole number inside the bounds its runs honour (its range and half to one and a half times its default). A value equal to the default removes the override; the whole save is refused when one value is not allowed. Each change is audited loop_param_override_set

Scope: admin.

Parameters

Request body (application/json)

Responses

• 200 {settings (as GET /v1/loops settings[]), changed: [{name, before, after}]}
• 400 invalid body, a setting the loop does not have (code unknown_setting), or a value out of range (code out_of_range)
• 403 admin scope required, or a read-only key
• 409 the loop was never turned on in this workspace (code not_set_up), or its settings kept changing (code busy)

GET /v1/loops/{id}/outcomes

What one loop found and what came of it (B6): its last runs, the items each staged with the decision and outcome (waiting, in_progress, declined, sent, rehearsed, applied, reversed, acknowledged, failed, blocked) and payments recovered after them, and its track record

Scope: read.

Parameters

Responses

• 200 {loopId, runs: [{id, startedAt, finishedAt, outcome, firstRun, sensed, eligible, staged, actions: [{id, actionType, status, outcome, createdAt, decidedAt, executedAt, recovered: [{currency, cents}], readback? (C6: a social post's 48-hour numbers)}]}], trackRecord, windowDays, week? (C6: founder-post only — What will post this week, as GET /v1/founder-post)}

GET /v1/loops/{id}/runs

A loop's 20 most recent runs (list_loop_runs)

Scope: read.

Parameters

Responses

• 200 {runs: [{runKey, startedAt, outcome, actionable, sensedCount, stagedCount, executedCount}]}

POST /v1/loops/{id}/run

Run a loop now (builtin, skill-compiled or dynamic). A call with an API key, from the CLI or from a dashboard session is a new run that senses again; dedupe and staged-action idempotency keys keep it from staging one signal twice. A call with an MCP OAuth token keeps one run per day (the runDate, default today UTC): a second call that day returns that run (resumed: true)

Scope: execute.

Parameters

Responses

• 200 harness result {outcome, actionable, resumed, sensed, eligible, staged, skippedByCooldown, skippedByDedupe, firstRun, selfCheck, logs, runId, startedAt, earlierRunStartedAt?}; resumed: true only for a window that already ran, with that run's recorded selfCheck and startedAt; earlierRunStartedAt: on a run that sensed again on a day the loop already ran (the tenant's time zone), when the latest earlier run that day started. B6: a listening loop that is on collects mentions first and adds collection (as POST /v1/tenant/listening/collect answers); a run whose self-check found no data adds remedies (what to connect, and where)

POST /v1/loops/{id}/stage-backlog

Stage the first-run backlog for review (admin; approval-gated loops only — nothing is sent)

Scope: admin.

Parameters

Responses

• 200 harness result (backlog: true)
• 409 regular runs already staging this loop
• 422 loop is not backlog-stageable

POST /v1/loops/failed-payment-dunning/stage-rehearsal

Stage the Day-0 sample recovery email (W5-A4): a made-up customer and payment, drafted by the recovery loop's drafter in the workspace's brand template and staged as a recovery_rehearsal card (payload.rehearsal: true). Approving it acknowledges it and sends nothing, to anyone; it counts as the session's first approval (the inbox checklist's hand-off) but in no metric. Nothing is read from Stripe. A waiting rehearsal is withdrawn when real work is staged

Scope: execute.

Responses

• 200 {rehearsal: true, stagedActionId, alreadyStaged, sent: false}; alreadyStaged: one was already waiting
• 403 read-only key
• 404 {error, code: rehearsal_not_found}: the workspace does not exist
• 409 {error, code: rehearsal_kill_switch | rehearsal_already_approved | rehearsal_real_work_waiting, waitingActionId?}: the kill switch is on (nothing could be approved), the workspace approved something already, or real work is waiting (its id)

POST /v1/loops/register-catalog

Register the 45-loop catalog + 2 platform loops into loop_registry (idempotent)

Scope: admin.

Responses

• 200 register report

GET /v1/marketing/operations

Read all 52 marketing skills, pinned methodology availability and actual native provider readiness

Scope: read.

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

GET /v1/marketing/accepted-artifacts/{workId}/{taskId}

Read exact accepted RevOps content and provenance for review context; not fact certification or a provider call

Scope: read.

Parameters

Responses

• 200 Exact UTF-8 artifact, original provenance and immutable acceptance; no Markdown field extraction.
• 403 Read scope required.
• 404 Missing, foreign, unaccepted, canceled, changed, erased or unverifiable source; no existence disclosure.

GET /v1/marketing/email-sequences/{runId}/{stepId}

Read the exact seven-message HTML handoff of a completed live source-exact email sequence; no provider calls

Scope: read.

Parameters

Responses

• 200 Full-source identity remains separate from deterministic escaped HTML; draft only, not delivery or model-quality proof.
• 403 Read scope required.
• 404 Missing, foreign, incomplete, rehearsed, changed or erased source; no existence disclosure.

GET /v1/marketing/work

List marketing work and result review dates

Scope: read.

Parameters

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work

Create a plan only; does not start tasks or approve external changes

Scope: execute.

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/plan

Propose a bounded cross-function work plan from company context; metered model call, no external approval

Scope: execute.

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

GET /v1/marketing/work/{id}

Read one work plan with task dependencies and execution evidence

Scope: read.

Parameters

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/revise

Replace a plan before acceptance; optimistic version check

Scope: execute.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/cancel

Close work; child Inbox decisions and applied changes retain their own state

Scope: execute.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/refresh

Refresh provider-confirmed progress; never infers delivery from an acknowledgement

Scope: execute.

Parameters

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/accept

Person accepts the plan only; context and version must still match

Scope: approve.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/confirm

Person accepts analysis or confirms outside work; optional displayed artifactHash binds exact bytes and methodology, never a native receipt

Scope: approve.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/review

Person records sourced results and next work; selected metrics need a trusted post-start observation

Scope: approve.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

POST /v1/marketing/work/{id}/tasks/{taskId}/start

Start a task after acceptance and prerequisites; native changes stage separate Inbox approvals

Scope: execute.

Parameters

Request body (application/json, required)

Responses

• 200 Tenant-scoped work record or capability inventory; execution evidence is read from governed child records.
• 403 Insufficient scope or person-only decision.
• 409 Stale version, changed context, prerequisites pending or provider evidence unavailable.
• 422 Invalid bounded input, date, task graph, metric or operation.

GET /v1/marketing-state

The tenant's marketing state (get_marketing_state; B1): ICP segments, goals with targets, channel priorities, budget envelope, named competitors, words to avoid and messaging pillars, with its version and newest 20 changes

Scope: read.

Responses

• 200 {version (0 = none yet), state: {icpSegments, goals, channelPriorities, budget, competitors, doNotSay, messagingPillars}, updatedAt, updatedBy, source: api|strategy|playbook|null, changelog: [{fromVersion, toVersion, fields, source, sourceRef, reason, proposedBy, acceptedBy, createdAt}], listeningCompetitors: {competitors: [{name, domain}] (the listening settings' companies), watched (every name monitoring watches: those companies, then the competitor search terms), match, onlyInMarketingState, onlyInListening (compared with watched)}}

PUT /v1/marketing-state

Replace the named marketing-state fields; the others keep their value (admin, audited). A change bumps the version and adds a changelog row; an unchanged write changes nothing

Scope: admin.

Request body (application/json)

Responses

• 200 the record (as GET) plus {changed, fields}
• 400 not an object, or no field named
• 403 read-only key or no admin scope
• 409 version_conflict: expectedVersion is not the current version
• 422 invalid_marketing_state: unknown key or invalid field, with issues [{path, message}]

POST /v1/marketing-state/competitors/monitors

C6 (#237) "Watch their pages" (admin, audited): context.dev monitors for each record competitor's home and pricing pages (an existing monitor for the page is used; a new one is tagged with the competitor's id), their ids kept on the record (a new version). At most 10 competitors

Scope: admin.

Request body (application/json)

Responses

• 200 the record (as GET) plus {monitors: [{id, name, monitorIds, created, pages, note}], changed}
• 403 read-only key or no admin scope
• 409 not_configured (no context.dev key), or version_conflict
• 422 no_competitors: no record competitor has a domain
• 502 monitors_failed: context.dev did not answer

GET /v1/marketing-state/competitors/{id}/battlecard

C6 (#237): one record competitor's battlecard, from the knowledge rows kept under its id: its latest page changes, its ads (running, new this week, the latest), its profile snapshots with the weekly follower change, beside its positioning notes

Scope: read.

Parameters

Responses

• 200 {battlecard: {competitorId, name, domains, positioningNotes, changes: [{title, url, importance, at}], ads: {active, newThisWeek, latest}, profiles: [{network, account, followers, followerDelta, windowDays, capturedAt}], rows, updatedAt}}
• 404 no competitor with that id on the record

POST /v1/mcp

MCP streamable HTTP on the official TypeScript SDK (spec 16, E2.6): protocol 2026-07-28 (server/discover + per-request _meta) and stateless 2025-era (initialize); JSON responses only. MCP Apps (io.modelcontextprotocol/ui, W2-6): resources/list and resources/read serve the inbox, weekly-brief and (W5-D4) metrics-pulse widgets (ui://, text/html;profile=mcp-app) at the read scope. W5-D4: prompts/list and prompts/get serve four read-only prompts (triage-approval-inbox, launch-product-campaign, diagnose-paid-efficiency, executive-weekly-brief) hydrated from the tenant's records, and resources/read serves heycmo://state/current and heycmo://brief/latest, all at the read scope

Scope: set per method and tool: read to list and read, the scope of the route a tool calls to act.

Responses

• 200 JSON-RPC result or JSON-RPC error
• 202 notification accepted
• 400 parse error (-32700), batch or invalid JSON-RPC (-32600), envelope/header mismatch
• 401 missing or invalid bearer token (WWW-Authenticate: Bearer realm="heycmo"; with MCP OAuth configured also resource_metadata=<RFC 9728 URL>)
• 403 insufficient_scope (OAuth tokens get a WWW-Authenticate step-up challenge naming the heycmo:* scope)
• 405 GET/SSE not offered

POST /v1/mesh/execute

Execute bounded specialist analysis with pinned skills and a shared context snapshot; return attributed, source-grounded paragraphs and explicit gaps. Optional technical audit reads only the verified site. No external writes. Each call starts a fresh analysis and may incur model costs; retries are not deduplicated.

Scope: execute.

Request body (application/json, required)

Responses

• 200 {mode, status: completed|partial|blocked, context, specialists, merged, technicalAudit, gaps, costCents, routeAuditId, auditId}; specialist paragraphs are model-written analysis, not execution receipts. Partial and blocked responses retain explicit evidence gaps.
• 400 Invalid input
• 403 Execution scope required or workspace restricted

POST /v1/mesh/route

Classify request → specialist delegations (spec 09, planning only)

Scope: read.

Responses

• 200 delegation plan

POST /v1/mesh/council

Run marketing-council recipe (spec 09 AC-3)

Scope: read.

Responses

• 200 council output

POST /v1/mesh/seo-audit

Plan seo-audit fan-out (spec 09 AC-2/AC-5)

Scope: read.

Responses

• 200 fan-out plan

GET /v1/mesh/coordinate

Coordinator's daily plan for the tenant (spec 09 AC-4). Issue #229: the plan the scheduler runs the tenant's day by, recorded once per tenant-local day (the scheduler or this route, whichever asks first) and returned as recorded, with the live state of its deferrals: run order, same-audience conflicts (a deferral proposal only when the move separates the loops), runs moved in from an earlier day and the advisory send budget. date defaults to the workspace's own today; a day not yet begun is a preview (planned: false)

Scope: read.

Parameters

Responses

• 200 tenantId, runDate, runOrder, conflicts, budget, auditId, planned, plannedAt, movedIn
• 400 date is not a calendar day

GET /v1/mesh/specialists

Specialist roster browse (spec 09)

Scope: read.

Responses

• 200 roster

GET /v1/metrics

Metric registry: every surfaced number with its definition, unit, source, freshness SLA and trust rule, plus the newest stored value and its freshness/trust

Scope: read.

Responses

• 200 {generatedAt, metrics: [{id, label, definition, unit, window, source, freshnessSlaHours, trustRule, collected, perCurrency, currency, annotated, latest: {date, value, source, observedAt, currency} | null, trust: {status, freshness, warning}}], collection}; money is one metric per currency (<family>.<currency>), never summed across currencies

GET /v1/metrics/pnl

The Marketing P&L over the trailing 30 days, one row per currency (money is never added across currencies): new MRR (stripe.new_mrr_cents_30d), recovered — the email-driven bucket only (recovery.email_driven_cents_30d) — paid spend (paid.spend_cents_30d), HeyCMO's cost (heycmo.cost_cents_30d.usd, on the USD row only: it is metered in US cents), net, a CAC proxy ((paid spend + HeyCMO cost on USD) ÷ new paying subscriptions, organic included) and payback months (CAC proxy ÷ ARPA), both estimates. Each figure cites its registry id; a figure the registry does not hold is null (not measured yet), never 0. The 30 days end today: a figure measured more than 3 days before today is marked stale (its value and date kept) and nothing is derived from it

Scope: read.

Responses

• 200 {generatedAt, windowDays, rows: [{currency, newMrr, recovered, paidSpend, heycmoCost, newPayingSubscriptions, arpa: {metricId, value, date, stale?: true}, net, cacProxy, paybackMonths: {value, from, missing, stale, formula}, notes}], heycmoCost}; a derived value is null when an input is missing or stale

GET /v1/metrics/targets

Each goal of the marketing state against the newest stored value of its own registry metric (same unit and currency by construction): met, ahead or behind by gap in the metric's unit (positive is the good side; a lower-is-better metric reads the other way), not_measured, or not_comparable (a money family without a currency, or an id HeyCMO does not measure), with the days left until its date

Scope: read.

Responses

• 200 {generatedAt, targets: [{goalId, label, metricId, unit, currency, target, by, current: {metricId, value, date}, state, gap, daysLeft, direction, reason}]}; direction is the metric's good direction ('up', 'down' for lower is better, 'neutral'; null for an id HeyCMO does not measure)

GET /v1/metrics/funnel

The funnel: sessions → key events → trials → new paying subscriptions, one row per day between two UTC days (default the 30 days ending today), with how many trials and new paying subscriptions the attribution ledger joined to a visit; the latest complete 30 days as the funnel collector wrote them; and the readiness line "Platform-reported conversions exceed Stripe conversions by N×" when the ad platforms claim at least 10 conversions and twice Stripe's new subscriptions or more

Scope: read.

Parameters

Responses

• 200 {from, to, rows: [{date, sessions, keyEvents, trials, paid, trialsJoined, paidJoined}] (null where a day has no value), latest: {sessions, keyEvents, trials, paid, trialsJoined, paidJoined, platformConversions, stripeNewSubscriptions: {metricId, value, date, trust}}, readiness: [{id, status, ratio, text, metricIds}], metricIds: {rows, latest}}
• 400 invalid range

GET /v1/metrics/{id}

One registry metric (an id with a dot): its definition, newest value and trust. A by-channel metric (acquisition.<event>.by_channel: one GA4 key event; acquisition.key_events.by_channel: every key event) also returns its rows per traffic source, medium and campaign with their channel group, and its totals per channel group, summed over a window (default the 28 days ending at its newest stored day); GA4's own session attribution, trusted only after tracking QA

Scope: read.

Parameters

Responses

• 200 {metric, latest, trust}; a by-channel metric adds {from, to, daysWithValues, total, complete, channels: [{source, medium, campaign, channelGroup, value, share}], byGroup: [{channelGroup, value, share}]} — the rows add up to the total; complete is false when GA4 cut its report
• 400 invalid range; currency_required (a money family) or event_required (the per-event family acquisition.key_event.by_channel), each with the tenant's ids
• 404 unknown metric id

GET /v1/metrics/{id}/series

Daily values of one registry metric between two UTC days (inclusive; default the 30 days ending today, at most 366)

Scope: read.

Parameters

Responses

• 200 {metric, from, to, points: [{date, value, source, observedAt}], latest, trust}; missing days are absent
• 400 invalid range, or currency_required: a money family is one metric per currency (<id>.<currency>), never a sum; ids lists the tenant's
• 404 unknown metric id

GET /v1/metrics/{id}/annotations

Applied external writes (budget changes, pauses, publishes…) the provider accepted live between two UTC days, on the channels that can move the metric, from the tenant's applied-write ledger; each with a before/after read of the metric labelled for trust and readiness — directional, never causal

Scope: read.

Parameters

Responses

• 200 {metric, from, to, scope: {channels, actionTypePrefixes?} | null, annotations: [{id, date, at, actionType, kind, label, title, channels, provider, externalRef, reversal, beforeAfter: {readiness, label, windowDays, before, after, difference, relativeChange, trust, causal: false, note}, target: {metricId, targeted, why}, readbacks: [{metricId, windowDays, changeDay, readiness, outcome, …}]}], more} — #235 target: the metric the write is meant to move (targeted: it is this chart's); readbacks: its recorded 14- and 28-day reads
• 400 invalid range, or currency_required for a bare money family
• 404 unknown metric id

GET /v1/metrics/recovery

Recovered revenue attribution

Scope: read.

Responses

• 200 recoveredCents30d … byClass; byStage (issue #232: notice, reminder, urgent, final, unrecorded — the stage of the credited send, per currency); liftOverStripe (recovery beyond Stripe Smart Retries, and the baseline rate from a dunning holdout or "not measured yet"); metricIds maps each number to its registry id

GET /v1/metrics/recovery/waterfall

W5-C4 (#284): the recovery waterfall of the failed invoices whose first failure fell in the last 30 or 90 days, each placed once, per currency (never added across currencies): failed (by decline category: expired_card, authentication_required, insufficient_funds, hard_decline, soft_decline, not_read); held with no email on purpose (a dunning holdout, the customer cancelled, Stripe ended the subscription); not emailed (paid before an email, waiting); emailed at least once live (by the furthest touch: notice, reminder, urgent, final); after the email: recovered and credited (Stripe's Smart Retries, cannot tell, beyond Smart Retries), paid but not credited, not recovered. Amounts are each invoice's amount still owed as last read, except what was recovered after an email: that is the payment credited to it (recovery_attribution, Stripe's amount_paid), with afterEmail.paidDifference the signed difference from what those invoices still owed; invoices with no amount are counted in withoutAmount, never as zero. The cohort is the payments that first failed in the window, not the payments made in it (GET /v1/metrics/recovery counts those), so the two figures can differ. The payback is the beyond-Smart-Retries money over the plan's published price for the same days, US dollars only; when the plan's cost cannot be known the payload says why instead of a number. latestRun: the latest full daily run's counts of invoices it left alone (paused or written off, left to Stripe's retries, final waiting for a scheduled retry)

Scope: read.

Parameters

Responses

• 200 {generatedAt, window: {days, from, to}, status: ready | no_failures | no_stripe, invoices, truncated, currencies: [{currency, failed: {invoices, cents, byDecline}, held: {invoices, cents, byReason: {holdout, customer_cancelled, stripe_ended}}, notEmailed: {…, byReason: {paid_before_email, waiting}}, emailed: {…, byTouch: {notice, reminder, urgent, final, unrecorded}}, afterEmail: {recovered, byClass: {smart_retries, unattributed, beyond_smart_retries}, paidDifference, paidNotCredited, notRecovered}, payback: {status: computed | unknown_plan_cost | other_currency, multiple, netCents, planCostCents, reason?}}], withoutAmount: {invoices, emailed, recovered}, latestRun: {at, pausedOrWrittenOff, leftToSmartRetries, finalWaitingForRetry} | null, preDunningSent, plan: {known: true, plan, interval, monthlyCents, currency, trialing} | {known: false, reason}}
• 400 days is not 30 or 90

GET /v1/metrics/attribution/models

W5-C4 (#284): one conversion's credit by channel group from the attribution ledger, read by every model side by side: first_touch, last_touch, u_shaped (40/20/40), time_decay (7-day half-life), shapley and markov (removal effect), each over the ledger's first and latest touch of every joined conversion (first, last, Shapley and Markov through W5-C2's compareAttributionModels); and mmm_marginal_roas from the marketing-mix fit the newest weekly review stored with its brief (W5-C2): each paid channel's contribution over the fit's own window and the cost of its next conversion with its 80% interval (the inverse of marginal ROAS), plus the model's baseline — unavailable, with the reason and no number, without a fit, with one that had too little data, with one whose own evidence test says the channels' spend explains the conversions no better than the weekday pattern and chance (fit.evidence.shown false, or no evidence stored), with any outcome but fitted, or with one fitted on the other conversion. No journey carries a value: every model credits conversions. Conversions no visit could be tied to are counted (noVisitor, noTouch), never spread. For new paying subscriptions each channel is also credited with first payments per currency (recorded since migration 20261122100000; older rows are counted as not recorded, never zero)

Scope: read.

Parameters

Responses

• 200 {generatedAt, conversion, window: {days, from, to}, status: ready | no_conversions | no_endpoint, conversions: {total, joined, noVisitor, noTouch}, firstPayments: {recorded, notRecorded, byCurrency: [{currency, minor}]} | null, truncated, models: [{id, label, what, available, unavailableReason, channels: [{channelGroup, credit, share, firstPayments: [{currency, minor}], rows?: [{source, medium, credit, share}]}], mmm?: {fittedAt, kpi, currency, window: {from, to, days}, conversions, rSquared, rSquaredBaseline, baseline, channels: [{channel, name, contribution, contributionInterval, marginalCpa, marginalCpaInterval, currentDailySpend}]}}]}
• 400 unknown conversion, or days outside 1..365

GET /v1/metrics/alpha

Compact alpha decision and recovery scorecard

Scope: read.

Responses

• 200 source-labelled alpha metrics; unknown values are null; metricIds maps each number to its registry id

GET /v1/onboarding

Onboarding readiness probes: the setup wizard and Settings checklist (Wave 9, E1.1)

Scope: read.

Responses

• 200 secrets/webhooks/sender/billing (plan, trial)/dunning/DRY_RUN/realDataLoops; productContext (one exists) and productContextDescribed (it describes the product: a model drafted it or a person wrote in it, not the blank template), which is what makes "Your website" done; brandKit (one exists) and brandKitDescribed (it has something in it: a colour, a font, a logo or a voice, not the empty kit a template draft stores), which is what makes "Your brand" done

POST /v1/onboarding/bootstrap

Automatic knowledge bootstrap {siteUrl, competitors?} — honest skipped[]. W5-A4: with or without context.dev it also reads the site's robots.txt, homepage and /llms.txt and stages one AI search check (geo_citability_audit: AI bots robots.txt lets in, the homepage on the GEO citability checklist, a drafted /llms.txt when the site has none)

Scope: admin.

Responses

• 200 ok, sitePages, monitors, brandStaged, geoStaged + skipped steps

GET /v1/operation-runs

List this workspace’s persisted operation runs, newest first (read scope)

Scope: read.

Parameters

Responses

• 200 {runs, count}: only this workspace’s runs
• 400 Invalid limit

POST /v1/operation-runs

Persist a validated, idempotent operation plan; does not execute it (execute scope)

Scope: execute.

Request body (application/json, required)

See the summary.

Responses

• 201 {run}: the persisted operation run, with bounded, secret-filtered response content
• 400 Invalid plan or input, unknown/unimplemented operation, forbidden fields or secret material
• 403 Insufficient scope, read-only identity or restricted workspace
• 409 The idempotency key belongs to a different plan

GET /v1/operation-runs/{runId}

Read one persisted run from this workspace (read scope)

Scope: read.

Parameters

Responses

• 200 {run}: the persisted operation run, with bounded, secret-filtered response content
• 404 Operation run not found, including another workspace’s run

POST /v1/operation-runs/{runId}/advance

Advance at most four steps of a leased operation run, with a 25-second request budget (execute scope)

Scope: execute.

Parameters

Request body (application/json)

Responses

• 200 {run}: the persisted operation run, with bounded, secret-filtered response content
• 400 Only maxSteps is accepted; no caller evidence, approval proof, output, or tenant identity
• 403 Insufficient scope, read-only identity or restricted workspace
• 404 Operation run not found, including another workspace’s run
• 409 Another request holds the lease, or the persisted execution contract changed

GET /v1/operation-runs/{runId}/steps/{stepId}/policy-review

Read a v1 fail-closed policy request (read scope)

Scope: read.

Parameters

Responses

• 200 {review}: exact stored scope, status and expiry. V1 never satisfies an applicable policy. V2 includes the unfiltered stored numeric proposal, exact OAuth account/connection, versioned review material, its hash, and append-only human decision events. Only the three qualified Google Ads reads can be reviewed; this is not legal or live-target validation.
• 400 Invalid identifiers or closed request body
• 403 Insufficient scope, restricted workspace, or decision attempted without a verified Clerk/WorkOS person
• 409 Stale, mismatched, expired, ineligible or already decided scope

POST /v1/operation-runs/{runId}/steps/{stepId}/policy-review

Record a v1 request, never an attestation (execute scope)

Scope: execute.

Parameters

Request body (application/json, required)

object

Responses

• 200 {review}: exact stored scope, status and expiry. V1 never satisfies an applicable policy. V2 includes the unfiltered stored numeric proposal, exact OAuth account/connection, versioned review material, its hash, and append-only human decision events. Only the three qualified Google Ads reads can be reviewed; this is not legal or live-target validation.
• 400 Invalid identifiers or closed request body
• 403 Insufficient scope, restricted workspace, or decision attempted without a verified Clerk/WorkOS person
• 409 Stale, mismatched, expired, ineligible or already decided scope

POST /v1/operation-runs/{runId}/steps/{stepId}/policy-review/{reviewId}/decision

Record a v1 negative decision by a signed-in person (approve scope)

Scope: approve.

Parameters

Request body (application/json, required)

Responses

• 200 {review}: exact stored scope, status and expiry. V1 never satisfies an applicable policy. V2 includes the unfiltered stored numeric proposal, exact OAuth account/connection, versioned review material, its hash, and append-only human decision events. Only the three qualified Google Ads reads can be reviewed; this is not legal or live-target validation.
• 400 Invalid identifiers or closed request body
• 403 Insufficient scope, restricted workspace, or decision attempted without a verified Clerk/WorkOS person
• 409 Stale, mismatched, expired, ineligible or already decided scope

GET /v1/operation-runs/{runId}/steps/{stepId}/privacy-review

Read the exact v2 human privacy review material (read scope)

Scope: read.

Parameters

Responses

• 200 {review}: exact stored scope, status and expiry. V1 never satisfies an applicable policy. V2 includes the unfiltered stored numeric proposal, exact OAuth account/connection, versioned review material, its hash, and append-only human decision events. Only the three qualified Google Ads reads can be reviewed; this is not legal or live-target validation.
• 400 Invalid identifiers or closed request body
• 403 Insufficient scope, restricted workspace, or decision attempted without a verified Clerk/WorkOS person
• 409 Stale, mismatched, expired, ineligible or already decided scope

POST /v1/operation-runs/{runId}/steps/{stepId}/privacy-review

Record an expiring resource-bound privacy request, without granting permission (execute scope)

Scope: execute.

Parameters

Request body (application/json, required)

object

Responses

• 200 {review}: exact stored scope, status and expiry. V1 never satisfies an applicable policy. V2 includes the unfiltered stored numeric proposal, exact OAuth account/connection, versioned review material, its hash, and append-only human decision events. Only the three qualified Google Ads reads can be reviewed; this is not legal or live-target validation.
• 400 Invalid identifiers or closed request body
• 403 Insufficient scope, restricted workspace, or decision attempted without a verified Clerk/WorkOS person
• 409 Stale, mismatched, expired, ineligible or already decided scope

POST /v1/operation-runs/{runId}/steps/{stepId}/privacy-review/{reviewId}/decision

Explicitly review, decline or revoke the displayed privacy scope as a Clerk/WorkOS person (approve scope)

API keys, CLI and MCP identities cannot decide, even without sign-in configured. Reviewer identity comes only from trusted authentication context. No input, policy list, resource override, approved boolean or arbitrary evidence is accepted. A reviewed event authorizes only this exact expiring workspace privacy scope; it never opens a Google Ads write guard.

Scope: approve.

Parameters

Request body (application/json, required)