API Documentation | Citewise AI

Authentication

Create an API key in Dashboard → Settings → API key. Keys start with cw_live_ and are shown once. Send the key as a bearer token:

curl https://getcitewiseai.com/api/v1/projects \
  -H "Authorization: Bearer cw_live_your_key"

Rate limits & errors

Up to 60 requests per minute per key. Errors return a JSON body {"error": "message"} with a standard HTTP status: 401 invalid key, 402 not enough credits, 404 not found, 409 run already in progress, 429 rate limited.

Projects

GET/api/v1/projects

List your projects with their latest visibility and citation rate.

{
  "projects": [
    { "id": "prj_…", "name": "YourBrand", "brand": "YourBrand", "domain": "yourbrand.com",
      "promptCount": 12, "engines": ["chatgpt", "perplexity"], "schedule": "weekly",
      "lastRunAt": "2026-10-06T09:00:00.000Z", "visibility": 0.58, "citationRate": 0.17 }
  ]
}

GET/api/v1/projects/{id}

Project report: latest run summary (visibility, share of voice, per-engine results, top sources), every check in the latest run and the trend across runs.

Runs

POST/api/v1/projects/{id}/runs

Start a run now. Credits for every prompt × engine are reserved immediately; failed checks are returned automatically. Returns 202 with the run id.

{ "runId": "run_…", "credits": 40, "checks": 40 }

GET/api/v1/runs/{id}

Run status and, once finished, its checks with the full answer, citations and analysis.

{
  "run": { "id": "run_…", "status": "done", "checksTotal": 40, "checksDone": 40, "creditsSpent": 40 },
  "checks": [
    { "prompt": "best invoicing app for freelancers", "engine": "chatgpt", "status": "ok",
      "brandMentioned": true, "brandPosition": 1, "brandCited": true,
      "competitorHits": { "Competitor A": 2 }, "citations": [{ "url": "https://…", "title": "…" }],
      "answer": "…" }
  ]
}

Quickstart: run a project and read the results

A typical integration starts a run, polls until it finishes, then reads the checks. Runs usually finish within one to three minutes.

const KEY = process.env.CITEWISE_API_KEY;
const api = (path, opts = {}) => fetch('https://getcitewiseai.com/api/v1' + path, {
  ...opts, headers: { Authorization: 'Bearer ' + KEY }
}).then(r => r.json());

const { runId } = await api('/projects/prj_123/runs', { method: 'POST' });
let result;
do {
  await new Promise(r => setTimeout(r, 5000));
  result = await api('/runs/' + runId);
} while (result.run.status === 'running');

const mentioned = result.checks.filter(c => c.brandMentioned).length;
console.log('Visibility:', mentioned / result.checks.length);

Each run reserves one credit per prompt per engine and returns credits for failed checks automatically, exactly as in the dashboard. See pricing for credit packs and how each metric is calculated.

Credits

GET/api/v1/credits

Current balance, split into free and purchased credits, with expiry dates.

{ "balance": 1840, "free": 25, "purchased": 1815, "lots": [ … ] }