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 the Pro, Agency and Scale plans. (The MCP connector is on every paid plan.)

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). Reports in Deleted are left out; add includeDeleted=true to list them too, marked deleted: true. • 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). A preset resolves in the workspace's time zone, as in the app, and the response carries the resolved dateRange. Add brandFilter=branded or brandFilter=nonbranded to read its Search Console widgets, and every other widget that counts search queries or keywords, for that group only. • GET /api/v1/ai-visibility/projects?clientId=… — your AI-visibility projects. • GET /api/v1/ai-visibility/projects/{id}/metrics?dateFrom=…&dateTo=…&model=…&market=…&source=… — AI-visibility metrics over whole UTC days (by default the last 30, at most 180): each brand pooled over every answer (answers naming it ÷ answers, with the answers as n and the ± margin), the client per engine, and the snapshot rows behind them, each with its engine label and source. Sentiment is on 0–100 with 50 neutral, and position 1 means named first; meta.note states the pooling rule. In /reports/{id}/data a KPI metric's prev is the comparison period's value. It is null when there is nothing to compare with: no comparison period, no earlier data for that metric, a comparison period the source could not be read for, or a figure that only exists as it stands today (catalog counts, review totals, follower totals). It is a number, 0 included, when the comparison period was measured: 0 is a real previous 0, from which there is no percentage change. Every KPI widget carries prevNull: true; meta.note says the same. A KPI metric's value is null when there is no figure: the read failed, or the value cannot be computed (for example cost per conversion with 0 conversions). It never stands for 0. A Search Console or Rank Tracking chart in /reports/{id}/data can carry googleUpdates: the Google ranking updates that ran during its dates, from Google's Search Status Dashboard (name, link, begin and end as US Pacific days, end null while still rolling out). They show timing only, not a cause, and meta.googleUpdates repeats that whenever a chart carries them. An AI-visibility source or citation widget in /reports/{id}/data (and in the MCP get_report_data) that left out answers whose URLs come from model memory, not a search, says how many: memoryExcluded on a table, donut or chart, fromMemory on each affected KPI metric. Those answers are in neither the numerator nor the denominator; the citation and content-gap endpoints report the same count as answersFromMemoryExcluded. An AI-visibility Brand table with a comparison can also carry withinMargin, the [row, column] cells whose change is not at least twice its margin of error: the report prints them grey with "~", so read such a change as unchanged. 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.