Already built for you

If you are integrating a product with Forumulate — an identity provider, a consent platform, a privacy orchestrator, a chat or knowledge vendor, a referral program — most of the plumbing you are about to write already exists. Read this page first. Each item names the one call that turns it on, and links to its reference.

Nothing here is specific to one vendor. Every contract on this page is Forumulate's own, published by Forumulate in its own machine-readable form. Where a named product appears (Atlas for sign-in, Cookie Munch for consent, Chatly for chat, Referalli for referrals), it is a preset over the same generic contract every other vendor uses.

The five you are most likely to rebuild by accident

Atlas readers: atlas_byo

If your product signs its users in with Atlas, readers on your docs, forum and blog are the same users with no route of yours in between. Forumulate verifies Atlas's own reader token (GET /v1/client/forumulate/reader_token on your Atlas frontend API), checks aud == forumulate:<orgId>, and keys members on (iss, sub). In a manifest it is one line: "readerAuth": "atlas". If your readers already sign in through external_jwt, GET /orgs/{orgId}/reader-auth answers a recommendations entry with the switch and the member relink to run first, and forumulate doctor --org <org> prints the same advice.

• Reader sign-in with your app: the Atlas recipe

/atlas/webhooks

Account changes at the identity layer — user.updated, user.banned, user.deleted, session.revoked — arrive signed and are applied here: a rename shows on every post, a ban suspends the member in every space within the minute, a deletion follows the privacy rules. You do not poll.

• Atlas, and who processes your data

• Lifecycle events

connector-providers

GET /orgs/{orgId}/connector-providers lists every chat and AI provider — ours and the ones your organization defined — with its fields, its embed, its consent category and how it reads your knowledge. Installing one is POST /orgs/{orgId}/spaces/{spaceId}/connectors; the knowledge feed and identity-in-chat work for all of them. A provider that holds a partner link of ours, or that we hold one to, needs no pasted API key.

• Chat and AI connectors

• The knowledge-source feed

• Give a third party read access

PUT /orgs/{orgId}/manifest

One document declares spaces, domains, reader sign-in, consent, connectors, the executor, webhooks, status monitors and the brand. PUT plans it (a dry run, with steps and their requires), ?apply=true carries it out with a read-back after every write, and GET …/manifest?export=true adopts an organization built by hand. Re-running a finished apply changes nothing.

• API conventions: the manifest operations

The privacy executor

Data-subject requests (access, deletion, closure, restriction, rectification) from any orchestrator — OneTrust, Transcend, DataGrail, Ketch, Osano, Cookie Munch, your own — through one documented HTTPS contract with signed completion callbacks. Mint the key with POST /orgs/{orgId}/privacy/executor-key (shown once; or give the orchestrator a partner link with privacy:execute instead), and it calls /privacy/executor/{orgId}/v2/*.

• Privacy executor contract (v2)

Sign-in with your own identity provider

Readers and members can sign in through any OIDC or OAuth 2 identity provider — Auth0, Clerk, Okta, Cognito, Keycloak, Firebase, Supabase, WorkOS, Entra — discovered from its issuer, or from your own app with a signed JWT. The provider's claims can carry a reader's principal, roles and personal values.

• Who may read, sign up and sign in to a space

• Sign readers in from your own app with a JWT

• Single sign-on: OIDC, SAML, DiscourseConnect and LTI

The embed manifest

Every host a reader page may load from, and every storage name it may write, published as one machine-readable file — so your security review and your consent platform's cookie scan start from a list, not a crawl.

• Embed manifest and the reader's Content-Security-Policy

Consent connect

One call connects a consent platform end to end: our side (webhook, executor, cookie manifest) done, and its side done or listed as steps. A platform that holds a partner link connects itself under it, with no key changing hands.

• Consent API reference

• The consent JavaScript contract

Provision an organization from one document

PUT /orgs/{orgId}/manifest takes one declarative document — spaces, and in version: 2 the units domains, reader_auth, consent, connectors, executor, webhooks, status_monitors and brand — and answers a per-unit plan (a dry run unless you send ?apply=true). Every planned and applied step carries the resource's id, and a re-run after a crash creates nothing twice. GET /orgs/{orgId}/manifest?export=true answers the organization as it is now, in the same shape, so an org built by hand can be adopted. Drive it from a script, or the owner's own tooling; there is no separate provisioning product to install.

The same document covers a whole content-as-code publisher too: each space's languages, SEO, translations, front door, contact form and About parts, pages from a Markdown folder with their Spanish (or any language's) twins, and the site around them. forumulate plan and forumulate apply build it from a forumulate.yaml and your folders.

• One file for the whole site: forumulate plan and apply

• Orchestrator-safe writes

Match the host page's brand

Every reader page publishes its brand as --forumulate-host-* CSS variables (accent, accent ink, surface, ink, line, radius, font and an always-visible focus ring), and the website SDK reads the same names from your page.

• Host-page variables

Credentials for partners and operators

• Partner links and token exchange

• Referral programs

Finding the contract

• GET https://forumulate.com/api/openapi.json — the whole API description.

• GET https://forumulate.com/changelog.json — every change to the contract a client could notice, newest first, as [{date, type, summary, affects}] (type is new, deprecation or behavior_change). A caller that states a Forumulate-Version, as every official SDK does, gets {entries: […]} instead; ?shape=entries or ?shape=array picks one. ?since=YYYY-MM-DD and ?type= filter it.

• /.well-known/api-catalog — an RFC 9727 catalog naming both, for tools that know only the domain.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go SDKs are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP agent server — its api_* family tools, or call_api. Where a CLI command or a hand-made MCP tool exists too, the last column names it. Operation names link to the API reference.

Connector Providers