---
title: "REST API"
url: "/docs/rest-api"
canonical_url: "https://crunchjunkie.io/docs/rest-api"
markdown_url: "https://crunchjunkie.io/docs/rest-api.md"
language: "en"
type: "doc"
summary: "Programmatic, read-only access to your reports and AI-visibility data with team-scoped API keys."
site: "CrunchJunkie"
llms_txt: "https://crunchjunkie.io/llms.txt"
---

# REST API
Source: https://crunchjunkie.io/docs/rest-api

Programmatic, read-only access to your reports and AI-visibility data with team-scoped API keys.

## What the REST API is
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.

## Creating an API key
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.

## Making a request
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).

## Endpoints
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.

## Rate limits, pagination and accuracy
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.