REST API

The CrunchJunkie REST API gives you programmatic, read-only access to the same data the app and the MCP connector expose — your clients, reports and their live data, and AI-visibility metrics — over plain HTTPS with JSON responses. It's built for servers, cron jobs, data warehouses and no-code tools like Zapier or Make: anywhere you want your CrunchJunkie numbers without a person clicking through the dashboard. Two things are true by design. It's read-only: every v1 endpoint fetches, nothing writes, so a leaked key can never change or delete anything or spend budget. And it's team-scoped: a key belongs to exactly one workspace and only ever returns that workspace's data. The API is available on paid plans (Pro, Agency, Scale), the same as the MCP connector.

Open Settings → API. Only a workspace owner or admin can create or revoke keys — a key can read the whole workspace, so it isn't a member-level action. Give the key a name (e.g. "Zapier production") and click Create. The full key — it looks like cj_live_ab12cd34.xxxx…​ — is shown exactly once. Copy it and store it somewhere safe (a secrets manager, your tool's credential field); we only ever keep a hash, so we can't show it to you again. If you lose it, revoke it and mint a new one. Revoking is instant: click Revoke on a key and any integration using it stops working on its next request. Keys don't expire on their own unless you set an expiry.

The base URL is https://app.crunchjunkie.io/api/v1. Send your key as a bearer token in the Authorization header: curl -H "Authorization: Bearer cj_live_ab12cd34.xxxx…" https://app.crunchjunkie.io/api/v1/clients Every response is JSON. Success looks like { "data": … , "meta": { … } }; an error looks like { "error": { "code": "…", "message": "…" } } with the matching HTTP status (401 unauthenticated, 403 wrong scope or plan, 404 not found, 429 rate-limited, 500 server error).

v1 is read-only and mirrors the MCP read tools, so the numbers match the app exactly: • GET /api/v1/clients — your clients, their connected providers and report counts. • GET /api/v1/reports?clientId=… — your reports (ids for the calls below). • GET /api/v1/reports/{id} — one report's definition (widgets, date config). • GET /api/v1/reports/{id}/data?datePreset=…&comparePreset=… — the report's live assembled data (KPIs, charts, tables). • GET /api/v1/ai-visibility/projects?clientId=… — your AI-visibility projects. • GET /api/v1/ai-visibility/projects/{id}/metrics?model=…&dateFrom=…&dateTo=… — snapshot metrics (visibility, share of voice, sentiment, average position, mention counts). The machine-readable OpenAPI 3.1 spec is published at https://app.crunchjunkie.io/api/v1/openapi.json — import it into Postman, Insomnia or your codegen of choice.

Each key gets a token-bucket rate limit; if you exceed it you get a 429 with a Retry-After header telling you how many seconds to wait. Large collections return the most-recent rows with a meta.total and a meta.truncated flag, so a capped page is never passed off as the whole set — narrow by date or model to reach older data. One accuracy note that matters if you compute your own aggregates: AI-visibility metrics follow the metric contract — pool a rate by summing the counts and the runs and dividing once (Σ visibilityCount ÷ Σ totalRuns), never by averaging per-row percentages, and keep each market (locale) as its own population. The app does this for you; do the same downstream and your numbers will match ours.