Developer overview

Cookie Munch is a self-hosted Consent Management Platform: a browser embed that does real prior-blocking of third-party scripts, a Node API server that stores an anonymised, tamper-evident consent ledger, and a set of typed clients (SDKs, an MCP server) built on top of one stable REST surface. This page maps what the platform offers, the resources you'll work with, and how the different developer-facing surfaces relate to each other.

What the API gives you

Everything a human can do from the Cookie Munch dashboard has a programmatic equivalent under /v1:

• Sites — register a property (cbid), verify domain ownership, read/write its banner + blocking configuration, fetch the install snippet.

• Consent — query aggregated stats, page through the anonymised consent log, export a CSV audit trail, verify the hash chain hasn't been tampered with, fetch a single subject's signed consent receipt, or crypto-erase a subject on request.

• Cookies & scanning — read the latest categorized cookie declaration for a site, and kick off (or poll) a Playwright-driven cookie scan.

• Banners — an account-level, reusable banner-library (themes/content you can assign across sites), separate from a single site's inline config.

• Privacy operations — DSAR (Data Subject Access Request) intake and lifecycle, a vendor risk register, and RoPA (Records of Processing Activities) entries — the governance tooling a DPO needs, exposed as CRUD.

• Org — members and roles, API keys (with scopes), webhook subscriptions, and a resource-usage summary against your plan's limits.

Every one of these resources is namespaced under a single org, and that org is derived from the API key you authenticate with — no request ever takes an orgId parameter. See Architecture for why that matters and how ownership is enforced.

The resource map

Full request/response shapes for each group live on their own reference pages (linked from the sidebar); this page is the map, not the manual.

The surfaces

Cookie Munch exposes the same underlying functionality through five different doors, each suited to a different caller:

1. REST (/v1/*) — the source of truth. Plain HTTP/JSON, authenticated with an fck_-prefixed API key (Authorization: Bearer or X-API-Key), versioned and stable. Every other surface is a client of this one. See Authentication & scopes and Conventions & errors.

2. @cookiemunch/sdk — a hand-written, typed TypeScript client (createCookieMunch({ apiKey, baseUrl })) wrapping /v1 with ergonomic methods (fc.sites.get(cbid), fc.consent.stats(cbid, { from, to })) and a CookieMunchApiError you can catch by .status. It tracks the API in the same monorepo release rather than being generated.

3. The embed's JavaScript API — window.CookieMunch, installed client-side by consent.js on a visitor's page. This is a different surface: it runs unauthenticated in the browser (no API key — it's public JS), exposes methods like .getConsent(), .updateConsent(), .showPreferences(), and is documented separately under JavaScript API. It talks to public, unauthenticated embed routes (/config, /consent, /impression), not /v1.

4. MCP server (@cookiemunch/mcp) — exposes a subset of /v1 (sites, config, consent stats/log, DSAR, vendors, RoPA) as tools for an AI agent (Claude Desktop, Claude Code, etc.), authenticated the same way as the SDK it's built on (COOKIEMUNCH_API_KEY env var). Useful for "ask an assistant to check consent stats" style workflows without writing integration code.

5. Webhooks — the only outbound surface. Subscribe a URL to events (consent.recorded, scan.completed, scan.cookies_changed, dsar.created, dsar.updated, banner.published) via POST /v1/webhooks, and the platform POSTs a signed (HMAC-SHA256) payload to you as things happen, instead of you polling /v1 for changes.

How they relate

The REST API is the only surface that talks to storage directly. The SDK is a thin wrapper generating the same HTTP calls you could make with curl; the MCP server is a thin wrapper around the SDK; the embed is architecturally separate — it never uses an API key and only ever talks to a handful of public, unauthenticated routes scoped to a single cbid. If you're deciding where to start: use curl against /v1 to explore, reach for the SDK once you're writing real code in TypeScript/JavaScript, and use the MCP server if the consumer is an AI agent rather than your own code.

A minimal read to sanity-check a key works:

curl https://api.cookiemunch.net/v1/me \
  -H "Authorization: Bearer fck_…"

{ "orgId": "org_9k2m", "plan": "pro", "keyPrefix": "fck_8f2a91c0" }

Next: Architecture for how the embed, API server, and ledger fit together, or jump straight to Authentication & scopes to issue a key.