API documentation (v1.2)

Authentication

Create a key on the API page (shown once; we store only its hash). Send it in the Authorization header of every request:

Authorization: Bearer co_live_xxxxxxxx...

Base URL: https://app.citationone.com. All endpoints live under /api/v1.

GET /api/v1/me

Quick key check — returns the account it belongs to and the key scopes.

curl https://app.citationone.com/api/v1/me \
  -H "Authorization: Bearer co_live_..."

# 200 ->
{ "userId": "...", "email": "you@example.com", "role": "user",
  "auditCredits": 20,
  "apiKey": { "id": "...", "scopes": ["audits:read","audits:write"],
              "webhookSecret": "9f2c..." },   // only with audits:write
  "apiVersion": "v1.2" }

Scopes decide what a key may do: audits:read — reading (GET /audits, GET /audits/{id}); audits:write — submitting audits and managing sharing (POST /audits, POST /audits/bulk, POST/DELETE /audits/{id}/share, POST /audits/bulk/{id}/cancel). A missing scope returns 403 insufficient_scope. Keys created in the panel get both, so existing integrations keep working unchanged.

POST /api/v1/audits — run an audit

Returns 202 immediately with a job id; the audit runs in the background (2–7 min). Then poll GET /api/v1/audits/{id}, or supply webhookUrl and skip polling entirely.

curl -X POST https://app.citationone.com/api/v1/audits \
  -H "Authorization: Bearer co_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-id-123" \
  -d '{
    "url": "https://example.com/article",
    "keyword": "target keyword",
    "language": "en",
    "project": "Acme Store",
    "share": false
  }'

# 202 ->
{ "id": "job_V1StGXR8...", "status": "queued", "createdAt": "2026-06-12T10:00:00.000Z" }

Parameters (JSON body):

The public report link (meta.shareUrl) is created only when you explicitly ask for it via "share": true — the example above uses false, the default, and the audit result is available only after logging into your account. To issue a link:

-d '{ "url": "https://example.com/article", "share": true }'

A report shared this way opens for anyone who knows the address — no login. The report language follows the audited content: ?lang=pl for Polish content, ?lang=en otherwise. Revoke the link in the app (report → Share → revoke) or via DELETE /api/v1/audits/{id}/share. Reading the result never issues or restores a link — publishing is always an explicit action. A report computed earlier without this flag can be shared via POST /api/v1/audits/{id}/share at no cost.

Headers:

• Idempotency-Key (optional) — the same request with the same key will not create a second audit or charge a second credit; it returns the existing job with 200. The parameters of the first request are binding: a retry with the same key but a changed share (or any other field) will not modify the job already created. If you want different parameters, use a different key.
• X-Request-Id (optional) — if you send one, we echo it back on every response and use it in our logs, which stitches your trace to ours. If you do not, we generate one. See "Limits and credits".

GET /api/v1/audits/{id} — status / result

Poll every ~15–30 s. status moves through: queued → running → completed (or error). {id} is normally a job id (job_…), but an audit id is accepted too — that is how you read an audit created in the app, which has no job (see ?source=all on the list).

# in progress ->
{ "id": "job_...", "status": "running", "auditId": "...",
  "project": "Acme Store", "createdAt": "..." }

# error ->
{ "id": "job_...", "status": "error", "errorCode": "crawl_failed",
  "errorMessage": "Failed to fetch page content", "createdAt": "..." }

# completed -> the full AuditResultV1 (below)
{ "id": "job_...", "status": "completed", "scores": { ... }, ... }

POST /api/v1/audits/bulk — many URLs in one request

Submits up to 50 URLs at once. They enter a queue and run one after another, and keyword data is fetched for the whole batch in one call instead of one per URL — which makes it cheaper and faster than looping over POST /audits.

curl -X POST https://app.citationone.com/api/v1/audits/bulk \
  -H "Authorization: Bearer co_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "project": "Acme Store",
    "urls": [
      { "url": "https://example.com/a", "keyword": "keyword a" },
      { "url": "https://example.com/b" },
      "https://example.com/c"
    ]
  }'

# 202 ->
{ "id": "V1StGXR8...", "status": "queued", "urlCount": 3,
  "project": "Acme Store", "apiVersion": "v1.2" }

• urls — 1 to 50 entries. Each is either a bare address ("https://…") or an object { url, keyword }. Without keyword the phrase is detected automatically.
• project — optional, assigns every audit in the batch to one project. The same tag as in POST /audits.
• Duplicate addresses are removed before the batch starts — otherwise the same URL would cost two credits.
• Credits: 1 per address we managed to fetch. Unreachable addresses are not charged. The balance is checked before any content is fetched, so insufficient credits give you a 402 immediately rather than several minutes in.
• One bulk request at a time per account. Another one while the first is still running returns 409 bulk_in_progress together with blockingBulkId — pass it to GET /api/v1/audits/bulk/{id} or to cancel, to unblock the account.
• Idempotency-Key (header, optional) — a retried request with the same key returns the same batch with 200 instead of starting a second paid crawl. Recommended for automated retries.
• A batch with no progress for 15 minutes (e.g. after a failure on our side) is closed automatically as error, and credits for audits that never started return to the account — the account is not left blocked for further batches.

The result is indistinguishable from individually submitted audits. A batch does not create a separate entity in the app: every audit shows up normally in the list, has its own job_… and is served by the same endpoints — reading the result, sharing, filtering by project. Bulk is purely a way of submitting.

Batch status: GET /api/v1/audits/bulk/{id}

{
  "id": "V1StGXR8...", "status": "running", "progress": 66,
  "urlCount": 3, "project": "Acme Store", "creditsCharged": 3,
  "counts": { "total": 3, "completed": 2, "failed": 0, "pending": 1, "skipped": 0 },
  "entries": [
    { "url": "https://example.com/a", "keyword": "keyword a", "status": "completed",
      "jobId": "job_...", "auditId": "...", "cqs": 72, "aiCitability": 6.4, "error": null }
  ],
  "apiVersion": "v1.2"
}

• One call returns per-URL scores for the whole batch — you do not need 50 separate GETs. Pass entries[].jobId to GET /api/v1/audits/{id} only when you want the full report for a given audit.
• status, both for the batch and for entries, uses the same vocabulary as single audits: queued, running, completed, error (batches add cancelled, entries add skipped).
• The counters sum to total, so you can read pending directly as "how many are left".
• Cancelling: POST /api/v1/audits/bulk/{id}/cancel — stops running audits and refunds credits for those that never started (creditsRefunded in the response). A batch that already finished returns 409.

Lost the identifiers? GET /api/v1/audits?bulkId=<id> returns every job from that batch, and each row of the list carries a bulkId field.

POST /api/v1/audits/{id}/share — public report link

Shares a report after the fact, for an audit already computed — without re-running it and without spending a credit. The link opens for anyone who knows the address, with no login. {id} is the job id, exactly as in GET /api/v1/audits/{id}.

curl -X POST https://app.citationone.com/api/v1/audits/job_.../share \
  -H "Authorization: Bearer co_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "shareExpiresInDays": 14 }'

# 200 ->
{ "id": "job_...", "auditId": "...",
  "shareUrl": "https://app.citationone.com/share/<token>?lang=en",
  "expiresAt": "2026-08-26T10:00:00.000Z", "apiVersion": "v1.2" }

# revoke access ->
curl -X DELETE https://app.citationone.com/api/v1/audits/job_.../share \
  -H "Authorization: Bearer co_live_..."

{ "id": "job_...", "auditId": "...", "shareUrl": null, "apiVersion": "v1.2" }

• The body is optional — a POST with no content shares without an expiry.
• shareExpiresInDays (1–365) sets an expiry counted from now. Omitting the field on an already-shared report leaves the existing expiry untouched — so re-sharing never silently extends access. An explicit "shareExpiresInDays": null removes the expiry (link never expires).
• An expired link comes back: a POST on a report whose expiry has passed removes that expiry and returns a working address (the same one as before). Pass shareExpiresInDays if it should be time-limited again.
• Idempotent: a repeated POST returns the same address. A link already distributed to clients is never invalidated by calling again.
• DELETE invalidates the link permanently and is idempotent too (a repeat call still returns 200). A subsequent POST issues a new address — the old one does not start working again.
• The audit must be finished: queued/running/error return 409 not_completed.
• Sharing and revoking do not change the audit's completedAt — this is an action on the link, not on the result.

After expiry meta.shareUrl in the audit result returns null, but meta.shareExpiresAt keeps the date — which lets you tell "the link expired" apart from "never shared".

GET /api/v1/audits — job list

Inventory and recovery of identifiers when you lose them on your side. Returns jobs (job_…) — the id from this list goes straight into GET /api/v1/audits/{id}.

curl "https://app.citationone.com/api/v1/audits?project=Acme%20Store&status=completed&page=1&limit=25" \
  -H "Authorization: Bearer co_live_..."

# 200 ->
{
  "data": [
    { "id": "job_...", "status": "completed", "auditId": "...",
      "project": "Acme Store",
      "input": { "url": "...", "keyword": "...", "language": "en" },
      "scores": { "cqs": 72, "aiCitability": 6.4 },
      "creditsCharged": 1, "errorCode": null,
      "createdAt": "...", "updatedAt": "...",
      "reportUrl": "https://app.citationone.com/audyt/..." }
  ],
  "page": 1, "limit": 25, "total": 137, "hasMore": true, "apiVersion": "v1.2"
}

Parameters (query string):

project filters on the current assignment: if an audit was moved to another project in the app, it appears under the new project, not the one given at submission time.

Picking up work started by a human. Pass ?source=all and the list also returns audits created in the app. Those have id: null and source: "panel" — they have no job, because nobody submitted them through the API. Address them by auditId: GET /api/v1/audits/{id} accepts an audit id just as it accepts a job_… id, so an agent can read a report a person started without any special casing.

What panel audits do not support: cancelling, retrying, Idempotency-Key and webhooks — all of those act on a job, and there is none. Sharing works normally, but through the app rather than POST /audits/{id}/share, which also addresses jobs. Fields carried by the job rather than the audit come back empty: errorCode is always null, and creditsCharged is reconstructed from the audit (0 if the credit was refunded after a failure).

One limitation stays. Sorting is newest-first, so an audit created while you page through shifts subsequent pages by one position. When dumping the whole history either walk the pages backwards (page descending) or de-duplicate by auditId.

Result: AuditResultV1

{
  "id": "job_...",
  "status": "completed",
  "createdAt": "2026-06-12T10:00:00.000Z",
  "completedAt": "2026-06-12T10:04:12.000Z",
  "input":   { "url": "...", "keyword": "...", "language": "en",
               "project": "Acme Store" },
  "scores":  { "cqs": 72, "aiCitability": 6.4 },
  "csi":     { "centralEntity": "...", "sourceContext": "...",
               "centralSearchIntent": "...", "predicate": "informational" },
  "dimensions": [
    { "id": "csiAlignment", "name": "...", "score": 7.5, "summary": "...",
      "strengths": ["..."],
      "problems": [ { "title": "...", "problem": "...", "suggestion": "...",
                     "impact": "high", "section": "...", "actionType": "add" } ] }
  ],
  "eeat": { "experience": 6, "expertise": 7, "authority": 5, "trust": 6, "average": 6.0 },
  "recommendations": [
    { "priority": "P1", "title": "...", "dimension": "chunk", "actionType": "add",
      "before": "...", "after": "...", "impact": "...", "estimatedCqsDelta": 3.2,
      "competitorUrls": [ { "url": "...", "domain": "..." } ] }
  ],
  "benchmark": { "keyword": "...", "searchVolume": 1900, "serpOrganicCount": 10,
                 "paa": ["..."], "related": ["..."] },
  "meta": { "creditsCharged": 1, "apiVersion": "v1.2",
            "reportUrl": "https://app.citationone.com/audyt/...",
            "shareUrl": "https://app.citationone.com/share/...?lang=en",
            "shareExpiresAt": null }
}

Webhooks — get notified instead of polling

Pass webhookUrl when submitting an audit and we will POST you the result once it finishes. An audit takes minutes, so polling in a loop costs you both requests and delay. It works the same for POST /api/v1/audits and POST /api/v1/audits/bulk — in a bulk request you get a separate event for each audit, exactly as if you had submitted them individually. There is no "whole batch done" event: audits from a batch are independent.

curl -X POST https://app.citationone.com/api/v1/audits \
  -H "Authorization: Bearer co_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "webhookUrl": "https://your-service.com/hooks/citationone"
  }'

Event payload (audit.completed or audit.failed):

{
  "event": "audit.completed",
  "job": {
    "id": "job_V1StGXR8...",
    "status": "completed",
    "auditId": "aud_...",
    "bulkId": null,
    "project": "Acme Store",
    "input": { "url": "https://example.com/article", "keyword": "...", "language": "en" },
    "creditsCharged": 1,
    "errorCode": null,
    "createdAt": "2026-08-13T10:00:00.000Z",
    "completedAt": "2026-08-13T10:04:12.000Z"
  },
  "apiVersion": "v1.2"
}

We send the event for failures too (audit.failed) — otherwise, having dropped polling, you would wait forever for something that never arrives.

Headers we send:

Verify the signature before trusting the payload. Your endpoint is public, and without verification anyone who learns its address can impersonate us and feed you a fake audit result. The secret is in GET /api/v1/me as apiKey.webhookSecret. It belongs to the account, not to an individual key, so it stays the same across all your keys.

apiKey.webhookSecret is returned only for keys with the `audits:write` scope — if the field is absent, that is why. The secret does not merely verify a signature: it also produces one, so a read-only key handed to a third party must not carry the ability to forge audit results into your pipeline. Read it with the same key you submit audits with.

import { createHmac, timingSafeEqual } from 'crypto';

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = parseInt(parts.t, 10);
  // Reject events older than 5 minutes — otherwise a captured request can be replayed.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  if (expected.length !== parts.v1.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

The signature is computed over "<t>.<raw body>", so verify against the raw request body — after JSON.parse and a re-stringify the bytes may differ and the signature will not match. The timestamp is inside the signed string on purpose: were it only a header, it could be swapped and an old event replayed indefinitely.

Delivery and retries:

• https is required (the event carries your audit result). Private and local addresses are rejected — including hostnames that resolve to one.
• We do not follow redirects — respond 2xx directly.
• Up to 3 attempts, with 1 s and 4 s pauses, and a 10 s response timeout. A 4xx (other than 408 and 429) ends the attempts immediately — that is a permanent error. A 3xx also ends them, since a redirect will be returned identically on every retry.
• A webhook is an acceleration, not a guarantee. If your endpoint was unavailable, the result still waits in GET /api/v1/audits/{id} — treat polling as your reconciliation fallback.
• A failure of your receiver never invalidates the audit or refunds the credit — the audit did run.

GET /api/v1/projects — project list

Returns the project names used across your audits, with an audit count and the date of the most recent one. Its purpose is to suggest existing names so a typo does not break grouping.

curl https://app.citationone.com/api/v1/projects \
  -H "Authorization: Bearer co_live_..."

# 200 ->
{
  "data": [
    { "name": "Acme Store", "auditCount": 42, "lastAuditAt": "2026-08-12T09:14:00.000Z" }
  ],
  "total": 1, "apiVersion": "v1.2"
}

There is no `projectId`, and no creating or deleting projects — this is deliberate. In this product a project is a label on an audit, not a separate entity: you assign it with the project field when submitting, and "moving" an audit means giving it a different name. An empty project could not exist, because there are exactly as many projects as there are names in use. Create a project simply by naming it in POST /audits — no separate call. Grouping is by EXACT name: "Acme Store" and "acme store" are two different projects.

The list covers all your audits, including those created in the app. That is why auditCount is sometimes larger than the number of results from GET /api/v1/audits?project=… — that list shows only audits submitted through the API.

GET /api/v1/credits/usage — balance and history

Credit balance together with the history of charges and top-ups — for automated budget control.

curl "https://app.citationone.com/api/v1/credits/usage?page=1&limit=50" \
  -H "Authorization: Bearer co_live_..."

# 200 ->
{
  "remaining": 128,
  "used": 372,
  "unlimited": false,
  "history": [
    { "type": "audit", "id": "aud_...", "delta": -1, "refunded": false,
      "url": "https://example.com/article", "project": "Acme Store",
      "createdAt": "2026-08-12T09:14:00.000Z" },
    { "type": "purchase", "id": "pay_...", "delta": 100, "refunded": false,
      "url": null, "project": null, "createdAt": "2026-08-01T12:00:00.000Z" }
  ],
  "page": 1, "limit": 50, "total": 373, "hasMore": true, "apiVersion": "v1.2"
}

remaining is the balance and the source of truth. used and history are reconstructed from your audits and payments, because charges have no separate ledger. That has three consequences worth knowing before you build a budget alarm on it: a manual balance correction by an administrator leaves no trace and will not appear here; administrator accounts do not pay for audits (unlimited: true, used: 0); and summing delta across the history need not reproduce the balance exactly. Use remaining to enforce a limit, and the history to account for where credits went.

A credit refunded after a failed audit has refunded: true and delta: 0 — the entry stays so you can see the attempt happened but cost nothing.

Errors

HTTP-layer errors have the shape { "error": { "code", "message", "requestId" } }. Some errors add fields beyond that — see "Extra error fields" below.

Extra error fields. Machine-readable detail on top of code/message, so you can validate on your side instead of parsing prose:

Frequent validation messages for `POST /audits/bulk`: urls must be a non-empty array (missing or empty body), Too many URLs (max 50 per request), each item needs a string url and each item must be a string or an object with a url (malformed entry), Invalid URLs in the list (n) (see invalidUrls[] above). All of them are 400 invalid_request.

When an audit fails in the background, GET returns status: "error" with errorCode and errorMessage. Possible errorCode values:

Limits and credits

• Credits: 1 audit = 1 credit. The credit is charged only after the content has been fetched and the CSI analysed (if preparation fails, no credit is taken). No refund once an audit fails mid-computation — same as in the app.
• Rate limit: 20 requests/min per key by default. Above that — 429 with a Retry-After header. Sharing (POST/DELETE /audits/{id}/share) and batch cancellation have their own separate windows, so heavy sharing does not eat into your budget for submitting audits.
• Limit headers: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds) come back on every response from the submission endpoints, not only on 429 — so you can throttle before you hit the limit.
• `X-Request-Id`: every response carries this header, and errors additionally carry error.requestId. Quote it in a support request and we will find your call in the log without guessing by timestamp. If you send your own X-Request-Id, we honour it and return the same value, which stitches our log to yours.
• Concurrency: at most 3 audits at a time per account (429 above that).
• Input limits: keyword ≤ 200 characters; project ≤ 100 characters; title ≤ 300 characters; content (fetched or supplied via content) 50–200,000 characters; bulk requests ≤ 50 addresses and one at a time per account.
• Key safety: we store only the hash — a lost key cannot be recovered, so create a new one and revoke the old.

Versioning

The path carries the major version, the apiVersion field the full one. All endpoints live under /api/v1 and that prefix will only change on a breaking change (then /api/v2, with v1 maintained until a deadline announced in advance). Additions that break nothing raise the number after the dot — which is why responses currently return v1.2 while you change not a single address.

apiVersion sits at the top level of every response. One exception: in the full audit result it lives under meta — that is where it has been since v1, and moving it would be exactly the breaking change we are avoiding.

What `v1.2` brought: webhooks on job completion, auditing content supplied directly (content instead of url), GET /projects, GET /credits/usage, date and domain filters on the job list, X-RateLimit-* headers on successful responses and X-Request-Id on errors. The earlier v1.1 added projects, the job list, sharing after the fact and bulk requests. All of it alongside existing fields — an integration written against v1 keeps working unchanged.