Install & initialize

Cookie Munch exposes its Developer API (the /v1 surface — sites, consent analytics, DSAR, vendors, RoPA, brand kits, preferences, members, keys, webhooks, and the reusable banner library) through typed clients in eight languages. Every client works the same way: construct it with an API key (fck_…) and your server origin, and the organization is derived server-side from the key — no client ever passes an orgId. That makes cross-org access structurally impossible from client code.

This page covers @cookiemunch/sdk, the primary TypeScript/JavaScript client, in depth, then lists install/init for the other six.

@cookiemunch/sdk (TypeScript / JavaScript)

Zero required dependencies beyond a fetch implementation. Runs in Node, Deno, Bun, and the browser.

npm install @cookiemunch/sdk
# or
pnpm add @cookiemunch/sdk
# or
yarn add @cookiemunch/sdk

import { createCookieMunch, CookieMunchApiError } from '@cookiemunch/sdk';

const client = createCookieMunch({
  apiKey: process.env.COOKIEMUNCH_API_KEY!,   // "fck_…"
  baseUrl: 'https://api.cookiemunch.net',      // /v1 is appended automatically — don't include it
});

const sites = await client.sites.list();
const site = await client.sites.create({ domain: 'example.com' }); // cbid auto-generated

CookieMunchOptions

Error handling

Every non-2xx response throws CookieMunchApiError { status, message, code? }:

try {
  await client.sites.get('unknown-cbid');
} catch (err) {
  if (err instanceof CookieMunchApiError) {
    console.error(err.status, err.message, err.code); // 404 "site not found" undefined
  }
}

message is the server's error field when the body was JSON, otherwise a generic request failed with status N. code is the server's code field when present (e.g. banner_in_use).

Injecting fetch for tests

import { vi } from 'vitest';

const mockFetch = vi.fn(async () =>
  new Response(JSON.stringify({ orgId: 'org_1', plan: 'free', keyPrefix: 'fck_test' }), { status: 200 }),
);
const client = createCookieMunch({ apiKey: 'fck_test', baseUrl: 'http://localhost:8787', fetch: mockFetch as unknown as typeof fetch });
await client.me();

Recording consent server-side

Most consent decisions come from the browser embed, but any client can also write directly to the tamper-evident ledger via the public, unauthenticated ingest endpoint (POST /api/v1/consent — no /v1 prefix, no API key):

await client.consent.ingest({
  cbid: site.cbid,
  stamp: crypto.randomUUID(),
  choices: { preferences: false, statistics: true, marketing: false },
  method: 'explicit',
  ver: 1,
  utc: Date.now(),
  url: 'https://example.com/checkout',
  subjectId: 'user_42', // optional — enables cross-surface consent lookups
});

Other-language SDKs

Every SDK below mirrors @cookiemunch/sdk's shape: one constructor call with an API key (org derived server-side), resource groups matching the /v1 surface 1:1, and a dedicated logConsent-style helper for the public ingest endpoint. Source lives under sdks/<lang>/ in this repo; see each folder's README for the full API.

All six default base_url/baseUrl to https://api.cookiemunch.net and accept an override for self-hosted deployments. Each also throws a dedicated error type on non-2xx responses (CookieMunchApiError in Python/Go/PHP, CookieMunchApiException in Java/PHP, ApiError in Ruby), carrying status, body/message, and code where the server sent one.

Quick-start reads for each:

# Python
from cookiemunch import CookieMunch
cm = CookieMunch(api_key="fck_your_key", base_url="https://api.cookiemunch.net")
sites = cm.sites.list()
cm.log_consent(cbid=site.cbid, choices={"statistics": True})

// Go
cm := cookiemunch.New("fck_live_your_key_here")
me, err := cm.Me(context.Background())
err = cm.Consent.Ingest(ctx, cookiemunch.ConsentIngest{Cbid: site.Cbid, /* ... */})

// .NET
using var client = new CookieMunchClient("fck_live_your_key_here");
var me = await client.MeAsync();
await client.Consent.RecordAsync(new ConsentRecordInput { /* ... */ });

# Ruby
cm = CookieMunch::Client.new(api_key: "fck_your_key")
cm.log_consent(cbid: "cbid_123", choices: { statistics: true })

// PHP
$cm = new CookieMunch\Client('fck_live_...');
$cm->logConsent(['cbid' => $cbid, 'choices' => ['statistics' => true]]);

// Java
CookieMunch cm = new CookieMunch("fck_live_...");
cm.logConsent(new ConsentIngest(site.cbid(), /* ... */));

Which client do I need?

• A website — you don't need any of these SDKs; install the consent.js embed directly (see Integrations).

• A backend service, CI job, or admin script managing sites/config/DSAR — use @cookiemunch/sdk or your language's REST SDK.

• A native/desktop app logging consent from its own first-run prompt — use your language's SDK's logConsent/RecordAsync/ingest helper against the public POST /api/v1/consent endpoint.

• An AI agent — see MCP setup; the MCP server is built directly on @cookiemunch/sdk.

Next steps

• Client reference — every client.* method on the TypeScript SDK, with signatures and examples.

• MCP setup — expose the same API as tools an AI agent can call.

• Webhooks & events — subscribe to client.webhooks.create(...) instead of polling.