OpenAPI spec

The entire /v1 developer API is described by a hand-written OpenAPI 3.1 document, served live and kept in lockstep with the actual route handlers — it's generated from the same server package, not maintained as a separate artifact that can drift.

GET /v1/openapi.json

This is the one unauthenticated route on the /v1 surface — no API key required, so tooling (API explorers, SDK generators, CI schema-diff checks) can fetch it freely.

curl https://api.cookiemunch.net/v1/openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cookie Munch Developer API",
    "version": "1.0.0",
    "description": "Stable, versioned developer API for Cookie Munch. Authenticate every request with an API key (`Authorization: Bearer fck_…` or `X-API-Key: fck_…`). The organization is derived from the key — never pass an orgId."
  },
  "servers": [{ "url": "https://api.cookiemunch.net" }],
  "security": [{ "ApiKeyBearer": [] }, { "ApiKeyHeader": [] }],
  "components": { "securitySchemes": { "...": "..." }, "schemas": { "...": "..." } },
  "paths": { "...": "..." }
}

Security schemes

Two equivalent schemes are declared — use whichever fits your HTTP client better:

Every operation in the document lists both under security, except GET /v1/openapi.json itself (security: []).

What's covered

The document enumerates every /v1/* path with per-operation summaries, parameters, request bodies, and response schemas — sites, config, consent stats/log/export, receipts, DSAR, vendors, RoPA, cookies, scans, A/B results, brand kits, preferences, members, keys, usage, webhooks, and the banner library — plus a handful of public (no-auth) /api/v1/... routes used by the embed itself (cookie-declaration feed, client-observed cookie ingest, cross-device consent profile sync).

Generating a client

Point any OpenAPI-3.1-compatible generator at the live document to produce a typed client in a language other than TypeScript. For example, with openapi-typescript:

npx openapi-typescript https://api.cookiemunch.net/v1/openapi.json -o cookiemunch.d.ts

Or with openapi-generator-cli for other languages:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.cookiemunch.net/v1/openapi.json \
  -g python \
  -o ./cookiemunch-client

Note: if you're on TypeScript/JavaScript, prefer the hand-written @cookiemunch/sdk — it ships richer types (enums, discriminated unions) than a generic OpenAPI codegen produces, and tracks the API in the same monorepo release.

Versioning

The document's info.version reflects the /v1 surface's semantic version. Because the prefix itself is /v1, breaking changes ship under a new prefix (/v2) rather than mutating this document's meaning out from under existing integrations — additive fields and new optional parameters can appear within /v1 without a version bump.