Skip to content
For AI agents & integrations

Cookie compliance an agent can set up on its own.

Everything the CookieCrumb dashboard does is available over a documented REST API with standards-based discovery. An AI agent — or a plain script — can register, create a site, prove domain ownership, run a cookie scan, install the consent banner, and read the audit log without a human clicking anything. This page is written for both of you: the developer evaluating the platform and the agent doing the work.

Discovery: start at one URL

Machine clients shouldn't need to scrape docs. CookieCrumb publishes its machine-readable surface at standard locations on this origin:

DocumentWhat it gives an agent
/.well-known/api-catalogRFC 9727 linkset — the single entry point. Links the OpenAPI description, human docs, OAuth metadata, and the health endpoint.
/openapi.jsonOpenAPI 3.1 description of the self-service API: auth, sites, config, geo rules, loader snippet, verification, scans, cookie categorisation, policies, team invites, stats, consent log.
/.well-known/oauth-authorization-serverRFC 8414 authorization-server metadata: authorization code + PKCE (S256) via /oauth/authorize, RFC 7591 dynamic client registration, token and revocation endpoints. Public clients only. Access tokens are HS256 (symmetric), so no jwks_uri is published — by design.
/.well-known/mcp/server-card.jsonMCP Server Card (SEP-2127) for the remote MCP server at the API's /mcp (Streamable HTTP, stateless). Reads: whoami, list_sites, get_site, get_site_config, get_setup_status (the onboarding checklist, naming the tool for each open step), get_stats, list_cookies, list_consents, list_scans, get_verification, get_policy, resolve_geo, list_team. Writes (owner/admin): create_site, update_site_config, set_geo, verify_domain, start_scan, categorize_cookies, invite_member. Deleting a site, billing and member role changes stay in the dashboard. Clients sign in with OAuth 2.1 — dynamic client registration, then authorization code + PKCE through the consent page — all discovered from the 401 → protected-resource metadata → authorization-server metadata; the same bearer token works on the REST API.
/.well-known/agent-skills/index.jsonAgent-skill discovery: a SKILL.md an agent can load to learn the whole adoption flow, with a content digest for integrity.
/llms.txtA plain-text site map for language models: what CookieCrumb is and where its docs, comparisons, and legal explainers live.

Authentication, precisely

The token endpoint is a spec-shaped OAuth 2.0 façade over the same auth the dashboard uses, so a non-browser client never has to deal with cookies. Being precise about what exists saves an agent three wasted requests:

  • Grants: authorization_code (with PKCE S256, for clients that register themselves via RFC 7591 dynamic registration), refresh_token, and password for non-interactive use. Public clients only, and no scopes — a token acts for its user.
  • Refresh tokens are returned in the response body (an API client has no cookie jar), are single-use, and rotate on every refresh.
  • Access tokens are HS256-signed JWTs. The signing key is symmetric, which is why the RFC 8414 document deliberately has no jwks_uri — there is no public key to publish. Verify possession by calling the API, not by validating the signature yourself.
  • Errors from the token endpoint use the bare RFC 6749 §5.2 shape ({"error": …}), not our regular error envelope.

The full lifecycle, eight requests

{api} is the API origin from the catalog's service links. Send Authorization: Bearer <access_token> on everything after step 2.

  1. 01

    Register an account

    POST {api}/v1/auth/register
{ "email": "[email protected]", "password": "…" }

    Returns the user and an access token. Non-browser clients follow up with the token endpoint to get a refresh token in the body.

  2. 02

    Get tokens (OAuth 2.1)

    POST {api}/v1/oauth/token
grant_type=password&[email protected]&password=…

    Interactive clients (MCP clients, apps) should register at /v1/oauth/register and use authorization code + PKCE through the /oauth/authorize consent page instead — see /auth.md. The password grant remains for non-interactive scripts. No scopes; refresh tokens are single-use and rotated on every refresh. Errors use the bare RFC 6749 §5.2 shape.

  3. 03

    Create a site

    POST {api}/v1/sites
{ "domain": "example.com" }

    The response carries the site id used in every subsequent path and in the loader URL.

  4. 04

    Read the install snippet

    GET {api}/v1/sites/{siteId}/loader

    Returns the exact <script> tag to place in the site's <head>, plus the public loader URL, hash, and size.

  5. 05

    Prove domain ownership

    GET  {api}/v1/sites/{siteId}/verification
POST {api}/v1/sites/{siteId}/verification/verify

    The GET mints a token with copy-paste instructions for all three proofs: a DNS TXT record, a /.well-known file, or a homepage meta tag. The POST runs all three checks and reports a reason per method. Verification gates scanning in production.

  6. 06

    Scan and read the inventory

    POST {api}/v1/sites/{siteId}/scan
GET  {api}/v1/sites/{siteId}/cookies

    The scan crawls the site and refreshes its cookie declaration; the cookies endpoint returns the categorized inventory.

  7. 07

    File what the scanner couldn't

    PATCH {api}/v1/sites/{siteId}/cookies
{ "cookies": [{ "name": "_xyz", "domain": ".example.com", "category": "Analytics" }] }

    Uncategorized cookies are gated by no banner toggle. A filed cookie keeps its category across re-scans; category null hands it back to the scanner.

  8. 08

    Configure the banner

    PATCH {api}/v1/sites/{siteId}/config
{ "text": { "title": "…" }, "policy": { "companyName": "…", "contactEmail": "…" } }
PUT   {api}/v1/sites/{siteId}/geo

    PATCH is a JSON Merge Patch — only the keys sent change, null restores a default; the OpenAPI description lists every key. PUT replaces the whole config, so avoid it. The served loader picks changes up within its 5-minute revalidation window.

  9. 09

    Read stats and the audit log

    GET {api}/v1/sites/{siteId}/stats
GET {api}/v1/sites/{siteId}/consents
GET {api}/v1/sites/{siteId}/consents/export

    Aggregates, a filterable consent log (choice, country, source, days), and a CSV export — the compliance artifact, machine-readable.

Guardrails an agent should know about

  • Verification gates scanning. In production a site must pass domain-ownership verification before it can be scanned. Do the DNS/file/meta step early; the verify endpoint tells you per-method why a check failed.
  • Patch the config, don't replace it. PATCH /config changes only the keys you send; PUT /config replaces everything and silently drops settings you didn't include.
  • Ask what is left. The MCP tool get_setup_status returns the onboarding checklist — verified, scanned, categorised, policy contact, loader live — and the tool for each open step.
  • Some actions are left to a human. The MCP server has no tool for deleting a site (it erases the consent log), billing, or changing and removing team members. The REST API can delete a site; confirm with the user before you do.
  • The consent ingest is not for you. POST /v1/consents is beaconed by the banner on real visitor decisions; it is origin-checked against the site's registered domain and rate-limited per IP.
  • Content usage signals: this site's robots.txt declares ai-train=no, search=yes, ai-input=yes — AI search and grounding welcome, training not.

Why we built it this way

More and more of our signups are performed by software: a developer tells an assistant "make my site cookie-compliant," and the assistant does the rest. That only works when the platform is honest about its machine surface — standard discovery documents, a spec-shaped token endpoint, an OpenAPI description that admits what doesn't exist. If you are a human reading this, the same API is yours to script. If you are an agent: start at /.well-known/api-catalog, and welcome.

For how the consent enforcement itself works — prior-blocking, the scanner, the audit log — see Why CookieCrumb and the documentation.

Point your agent at the catalog.

GET https://cookie.trishchuk.com/.well-known/api-catalog

Start freeView the OpenAPI spec