Connect Claude and use the API
Manage the same sites, checks, findings, and monitoring from Claude Code or your scripts.
5 min readOn this page
Documentation for your agent
The copied Claude setup message starts with a link to the public Markdown guide. It includes this help, a first-audit walkthrough, fix verification, and operation input schemas generated from the API validators. Agents can fetch it without signing in or sending your API key. After connecting, discover the MCP tools for their current schemas.
Create a workspace API key
- Sign in, select the workspace you want your tools to use, and open API & MCP.
- On a new workspace, select Create key & connect Claude. Or create a named Development or Read-only key with your preferred expiry in API & MCP. Select Copy setup for Claude while the new key is shown.
- Optionally restrict audit targets to exact website origins. A blank list allows any supported public target in the connected workspace.
Each key stays bound to one workspace. It reads the same sites, results, and persistent findings as your dashboard, including records created before the key. A replacement key retains access to that workspace’s history. Switching workspaces in the app does not move an existing key.
Connect Claude Code
Paste the copied setup message into Claude Code. It includes your new API key, the hosted MCP address, a ready-to-run connection command, and instructions for the first audit. Claude can configure its connection and tell you if a restart is needed. The message is private and shown once; if you close it before copying, create a replacement key. You can also use the manual command or environment-based .mcp.json configuration in API & MCP. No local Cookie Trail server is needed.
Ask Claude to read your workspace and usage, list or add sites, run an audit, inspect findings, and propose fixes after reading your repository. After you deploy the change to the same public URL, ask it to rerun and compare the audit. The API-key connection is supported by clients that can send a bearer header; browser-based OAuth connection is not implemented.
For other MCP clients, use https://cookietrail.app/api/mcp with Streamable HTTP and the header Authorization: Bearer YOUR_API_KEY. The server exposes 21 tools with their request schemas. In Claude Code, the manual command is: claude mcp add --transport http --scope user cookie-trail https://cookietrail.app/api/mcp --header "Authorization: Bearer YOUR_API_KEY". Replace YOUR_API_KEY with the key you just created.
Use the REST API
Requests use https://cookietrail.app/api/agent and Authorization: Bearer YOUR_API_KEY. Responses are not cached. Error responses include a code and message. Check the workspace and usage before starting work.
| Operation | Endpoint |
|---|---|
| Read or rename workspace | GET /workspace · PATCH /workspace |
| Read usage | GET /usage |
| List or register sites | GET /sites?limit=30 · POST /sites |
| Read or edit a site | GET /sites/:siteId · PATCH /sites/:siteId |
| Archive or restore | POST /sites/:siteId/archive |
| List or start audits | GET /audits · POST /audits |
| Read audit evidence and briefs | GET /audits/:auditId |
| Verify and compare | POST /audits/:auditId/rerun · GET /audits/:auditId/compare?baselineId=… |
| Read or review persistent findings | GET /findings · GET /findings/:issueId · PATCH /findings/:issueId |
| Verify a finding | POST /findings/:issueId/verify |
| Read, enable, or pause monitoring | GET /sites/:siteId/monitoring · PUT /sites/:siteId/monitoring · DELETE /sites/:siteId/monitoring |
Send JSON bodies with Content-Type: application/json and your Authorization header. The examples below use SITE_ID, AUDIT_ID and ISSUE_ID from earlier responses; replace those placeholders before sending. Requests never need a workspace ID: your key selects the workspace.
| Request | JSON body |
|---|---|
| PATCH /workspace | {"name":"My workspace"} |
| POST /sites | {"url":"https://example.com/","name":"My site"} |
| PATCH /sites/SITE_ID | {"name":"My renamed site","url":"https://example.com/new-page"} |
| POST /sites/SITE_ID/archive | {"archived":true} (use false to restore) |
| POST /audits | {"siteId":"SITE_ID","region":"de","requestId":"first-audit-001"} |
| POST /audits/AUDIT_ID/rerun | {"requestId":"verify-deployment-001"} |
| PATCH /findings/ISSUE_ID | {"expectedRevision":0,"status":"in_progress","note":"Investigating consent gating","ticketUrl":"https://example.com/issues/123"} |
| POST /findings/ISSUE_ID/verify | {"requestId":"verify-finding-001"} |
| PUT /sites/SITE_ID/monitoring | {"region":"de","cadence":"weekly","hour":12,"minute":0,"weekday":1} |
| DELETE /sites/SITE_ID/monitoring | No body; pauses the schedule. |
The name is optional when registering a site, but required when editing it; the edited URL is optional. Region values are de, uk, us-east, us-west, ca and sg; omitted audit region defaults to de. Monitoring accepts weekly or daily; time is UTC, hour is 0–23, minute 0–59, and weekday is 0 (Sunday) through 6 (Saturday). Review status is open, in_progress, resolved or dismissed; note, status, ticketUrl and assigneeId are optional. Copy expectedRevision from the issue’s current revision, and use a member userId for assignment or null to clear it.
Site registration returns {siteId,url,name,reused}; site detail returns {site,...}, with site._id as the ID. Starting or rerunning a check returns {auditId,siteId,status,url,region,reused}. Retrieve GET /audits/AUDIT_ID until status leaves queued/running; complete, inconclusive and failed are terminal states. Inspect result.coverage and result.findings before deciding whether a fix worked. Result findings belong to that audit; lasting review and verification use ISSUE_ID from the persistent finding list.
Site, audit and finding lists return {sites|audits|issues,...,nextCursor}. Follow every non-null nextCursor as the cursor query parameter, even if the page is empty; keep filters unchanged. Sites and audits accept limit from 1 to 100. Audit filters are siteId, region and status. Persistent finding entries expose issueId (also _id) and revision. Finding detail returns {issue,history,historyCursor,...}; follow historyCursor as cursor for its history. To compare terminal audits, use GET /audits/AUDIT_ID/compare?baselineId=OLDER_AUDIT_ID. It returns resolved, stillPresent, new, inconclusive and coverage for the same site URL/location.
Access follows your current workspace role
Development keys can add and edit sites, start checks, review findings, and configure monitoring where the current role and plan allow. Read-only keys can inspect the workspace, usage, sites, evidence, and finding history. Renaming the workspace and managing monitoring require its current owner. Teammate assignment requires that plan capability. Keys cannot manage payments, membership, or create other credentials.
Checks started through the API and scheduled monitoring use the same workspace allowance as the dashboard. Reopening an active check uses no extra slot. Missing consent coverage remains inconclusive; reviewing a finding as resolved does not establish that the measured behavior was fixed.
You can revoke your own keys or make them read only. The workspace owner can manage every key in the workspace. Expired and revoked keys stop working on the next request. Leaving or being removed from the workspace disables your keys. Saved evidence remains available to current members.