Getting started, FAQ, and troubleshooting

You are integrating the CiteFlow Partner API into <MY APP NAME>. This integration FIRES audits from my code and reads results synchronously — I do NOT run a webhook endpoint. Use ONLY the info below; do not invent endpoints or behaviour.

## API basics
- Base URL: https://www.citeflow.io/api/v1
- Auth: Authorization: Bearer ckf_<my-key>
- Content-Type: application/json on POST
- Every success response: { "data": { ... }, "request_id": "req_..." }
- Every error response: { "error": { "code": "...", "message": "...", "doc_url": "..." }, "request_id": "..." }
- Every POST MUST include header  Idempotency-Key: <uuid-v4>. The SAME key MUST be reused for every retry of the same logical operation — do NOT mint a fresh key per retry, or you risk double-charging on a network blip.

## Endpoints I will use

### POST /audit  — create an audit
Body: { "url": "https://example.com", "type": "all" | "seo" | "aeo" | "geo", "metadata"?: { ... } }
Returns 202: { "data": { "audit_id": "...", "status": "queued", "type": "...", "credits": { "charged": number /* 80 for seo|aeo|geo, 150 for all */ } } }

### GET /audit/{id}  — poll status / read result
Returns 200: { "data": { "audit_id": "...", "status": "queued" | "processing" | "complete" | "failed" | "cancelled", "scores"?: { "overall": 73, "seo": 78, "aeo": 65, "geo": 70 }, "dimensions"?: { "technical": 80, "crawlers": 95, "schema": 70, "citability": 74, "platform": 80, "content": 78, "brandMentions": 65 }, "issues"?: [ ... ], "failure_reason"?: "timeout" | "engine_error" | "blocked_by_policy" | "partner_input" | "cancelled_by_user", "credits": { "charged": number, "refunded": number } } }
Treat credits.charged and credits.refunded as plain numbers. Typical values: charged 80 or 150; refunded 0 / 50% on engine-side failure / 100% on cancel. Do NOT model them as a closed enum — the refund matrix may evolve.

### POST /audit/{id}:cancel  — abort while still queued / processing
Refunds 100% of charged credits.

### GET /balance  — current credit balance
Returns: { "data": { "balance": 4900, "balance_usd": "$49.00", "lifetime_purchased": 4900, "lifetime_consumed": 0 } }

## Credit costs per audit
- type=all: 150 credits ($1.50, full SEO+AEO+GEO bundle)
- type=seo | aeo | geo: 80 credits ($0.80) each

## Reliability patterns
1. Auto-retry on 429 and 5xx with exponential backoff. Honor Retry-After if present.
2. For each logical POST, generate ONE fresh UUIDv4 Idempotency-Key and reuse it across ALL retries of that operation. Do NOT generate a new key per retry.
3. Polling helper: call GET /audit/{id} every 3 seconds until status is terminal (complete | failed | cancelled). Overall timeout 90 seconds; surface a clean timeout error to my caller if exceeded.
4. Log request_id on every API error. Never log API keys.

## Official SDKs — prefer these over hand-rolling HTTP
- Node.js: `npm install @citeflow/sdk`. Exposes a Citeflow class with .audits.create() / .audits.waitForCompletion() / .audits.get() / .audits.cancel() / .balance.retrieve().
- Python: `pip install citeflow-python`. Same surface, snake_case (audits.wait_for_completion(), etc).

### SDK return shape
- On success, SDK methods return the UNWRAPPED "data" object (e.g. `client.audits.create()` returns { audit_id, status, credits, ... } directly — NOT the { data, request_id } envelope).
- On failure, methods RAISE a typed CiteflowError with .code / .message / .requestId (Node) or .request_id (Python) / .docUrl / .status. Log those fields, never the raw exception.

### Use SDK helpers, don't re-implement
The SDKs already ship: auto-retry on 429+5xx with backoff + Retry-After, auto Idempotency-Key (with proper reuse across SDK-internal retries), and waitForCompletion polling. USE THOSE. Fall back to raw fetch / requests only for behaviour the SDK does not provide.

## What I want you to build
<<< DESCRIBE THE FEATURE — for example:
"Add a Scan button to my Next.js admin page that scans a URL via the SDK's waitForCompletion helper and renders overall + seo + aeo + geo scores in a result card. Include a Jest test that mocks the SDK."
"Write a Python script that reads urls.txt, scans each URL with type=all in parallel (max 4 concurrent) using the SDK's wait_for_completion, and writes results to results.csv." >>>

## Constraints
- Use the official SDK if one exists; otherwise raw fetch / requests.
- Read CITEFLOW_API_KEY from environment — never hardcode.
- Log request_id on every error so I can quote it in a support ticket.
- Write at least one happy-path test that mocks the SDK / fetch (no live API calls).
- Include a short README section with env-var setup + a demo command.
- When an SDK method signature, package import, or return shape is not explicitly stated above, make the smallest reasonable assumption, tag it with a "// ASSUMPTION:" comment, and isolate it behind a tiny adapter so it can be corrected in one place. Do NOT invent endpoints, response fields, or behaviours.

You are integrating the CiteFlow Partner API into <MY APP NAME> using the ASYNC pattern: my server fires audits, CiteFlow scans in the background, then CiteFlow webhooks the final result to MY server, which surfaces it to the user. Build the COMPLETE flow — outbound trigger + inbound webhook + a path to deliver results to the frontend — so a user in my product can submit a URL and eventually see the scan results. Use ONLY the info below; do not invent endpoints or behaviour.

(Pick this pattern when scans run in the background and the user doesn't sit waiting on a single request — also better when scan volume scales. If the user is staring at a spinner expecting an immediate response, use the Outbound polling prompt instead.)

## API basics (for outbound calls FROM my code TO CiteFlow)
- Base URL: https://www.citeflow.io/api/v1
- Auth: Authorization: Bearer ckf_<my-key>
- Content-Type: application/json on POST
- Success: { "data": { ... }, "request_id": "req_..." }
- Error: { "error": { "code": "...", "message": "...", "doc_url": "..." }, "request_id": "..." }
- Every POST MUST include header  Idempotency-Key: <uuid-v4>. The SAME key on every retry of the same logical operation. Do NOT mint a new key per retry attempt.

## Endpoint I will call to TRIGGER audits

### POST /audit
Body: { "url": "https://example.com", "type": "all" | "seo" | "aeo" | "geo", "metadata"?: { ... } }
Returns 202: { "data": { "audit_id": "...", "status": "queued", "type": "...", "credits": { "charged": number /* 80 for seo|aeo|geo, 150 for all */ } } }
Return the audit_id to my caller immediately and STOP. Do NOT poll GET /audit/{id} from this path — the webhook will deliver the final result.

## Endpoint I may call as a fallback safety net

### GET /audit/{id}
Use ONLY if a webhook is suspiciously late (e.g. > 5 minutes past queued without a delivery). If the audit shows a terminal status here but my scans row is still pending, mark the scan as status='webhook_missing' and surface an alert. Do NOT try to auto-replay — the replay endpoint needs a delivery_id which is not available from GET /audit/{id}.

### POST /webhooks/deliveries/{delivery_id}/replay (informational — usually NOT called from partner code)
Authorization: Bearer ckf_<my-key>. delivery_id is the per-delivery attempt identifier from the CiteFlow dashboard webhook log — it is NOT the same as event.id, audit_id, or X-CiteFlow-Webhook-Id. Do NOT guess or derive it. Replay is usually driven from the dashboard UI by a human operator. Only implement automatic replay if my feature description below explicitly provides a delivery_id source.

## Credit costs per audit
- type=all: 150 credits
- type=seo | aeo | geo: 80 credits each

## What I receive via webhook (inbound)
CiteFlow POSTs to MY endpoint URL (registered manually at /dashboard/api/webhooks — not an API call) when an audit terminates or balance crosses a threshold. Event types fall in two groups:

### Audit events (audit.completed | audit.failed | audit.cancelled)
{
  "id": "evt_...",
  "type": "audit.completed",
  "created_at": "2026-06-02T10:00:00Z",
  "data": {
    "audit_id": "...",
    "url": "...",
    "scores"?: { "overall": 73, "seo": 78, "aeo": 65, "geo": 70 },
    "failure_reason"?: "timeout" | "engine_error" | "blocked_by_policy" | "partner_input" | "cancelled_by_user",
    "credits": { "charged": number, "refunded": number }
  }
}
Treat credits.charged and credits.refunded as plain numbers, not a closed enum.
The webhook payload is a SLIM summary — it does NOT include dimensions, issues, or fixes. If my feature needs those details, call GET /audit/{audit_id} ONCE from the webhook handler (or a queued job) after verifying the signature, and store the full result.

### Balance event (balance.low)
Fires once when my credit balance crosses below the low-balance threshold. The data shape is DIFFERENT from audit events — do NOT assume audit_id, url, scores, failure_reason, or credits.charged/refunded exist on this event. If my feature doesn't explicitly handle balance.low, just log it and return 200. Do NOT route balance.low through the audit_results upsert path.

## Webhook verification (CRITICAL — HMAC-SHA256, constant-time compare)
Headers on every delivery:
- X-CiteFlow-Webhook-Id: evt_...
- X-CiteFlow-Webhook-Timestamp: <unix-seconds>
- X-CiteFlow-Webhook-Signature: v1=<base64-hmac-sha256>

Algorithm:
1. Reject if timestamp drift > 300 seconds (5 minutes). Prevents replay.
2. signed_payload = byte concat of  `${webhook_id}.${timestamp}.${raw_request_body}` where webhook_id is the exact value of the X-CiteFlow-Webhook-Id HEADER (NOT body.id — the body must not be parsed before verification) and timestamp is the exact value of X-CiteFlow-Webhook-Timestamp. raw_request_body is the raw request body bytes BEFORE any JSON parsing.
3. HMAC-SHA256 with my endpoint's signing secret. Base64-encode the digest.
4. Constant-time compare against the v1= value.
5. Header may carry "v1=old,v1=new" during a 7-day secret rotation grace period. Accept ANY matching value.

## Idempotent processing — MUST IMPLEMENT
Webhook deliveries may be retried by CiteFlow or replayed manually. Process every event idempotently:
- Use event.id as the dedup key (UNIQUE constraint on a processed_events table OR check-then-upsert in my audit_results table).
- For audit events, data.audit_id is also a valid dedup key — only one terminal event fires per audit.
- Duplicate deliveries must produce ZERO side effects. Design DB writes as UPSERTs.
- If a delivery is recognised as a duplicate (already-processed event), return 200 with no body. Do NOT return 409 or 500 for duplicates — that would make CiteFlow's delivery retries hammer the endpoint.

## App-level idempotency for scan triggers (different from CiteFlow's Idempotency-Key)
CiteFlow's Idempotency-Key only deduplicates retries of the SAME outbound POST /audit call. It does NOT protect against a user double-clicking the Scan button or my frontend retrying my own POST /api/scan endpoint — both of those produce two DIFFERENT logical operations from my server's perspective and would create two CiteFlow audits, charging me twice.

Add a second layer of dedup on MY trigger endpoint:
- Accept a client-supplied request_id (UUID from the browser) OR derive a server-side key from (user_id, url, type, time_bucket).
- Store it on the partner scans table with a UNIQUE constraint. If the same logical scan arrives twice within a short window, return the existing audit_id instead of firing a second POST /audit.
- This is separate from, and required IN ADDITION TO, CiteFlow's Idempotency-Key on the outbound call.

## Partner-owned scan status lifecycle
Use these statuses on MY scans table so the frontend, DB queries, and downstream logic agree:
- pending: I called POST /audit and got 202; waiting for the webhook.
- complete: audit.completed processed; scores stored.
- failed: audit.failed processed; failure_reason stored.
- cancelled: audit.cancelled processed.
- webhook_missing: fallback check (see below) found a terminal audit at CiteFlow but no webhook ever stored a result for me. Surface this to an operator.

## Reliability for my endpoint
- Return 200 within 5 seconds of successful verify + idempotent process. Heavier downstream work → enqueue then ACK 200 immediately, process async.
- On signature mismatch, return 400 and do NOT enqueue, store, or internally retry the event. Treat it as a security failure.
- CiteFlow auto-disables the endpoint after 10 consecutive non-2xx responses (400s from signature mismatch count). Alert on signature-mismatch spikes — repeated mismatches will get the endpoint auto-disabled and silently drop legitimate deliveries until I re-enable in the dashboard.

## Raw body capture — framework-specific gotchas
- Express: `app.post('/webhooks/citeflow', express.raw({ type: 'application/json' }), handler)`
- Next.js Route Handler: `const raw = await req.text(); /* verify with raw */; const event = JSON.parse(raw);`
- FastAPI: `raw = await request.body()`
- Most frameworks auto-JSON-parse the body and break verification. Always grab raw bytes first.

## Getting the result to MY frontend (closing the loop)
The webhook handler writes the result to my server-side DB. To surface it to a user in my UI, pick ONE:
- DB poll: frontend polls a partner-owned endpoint like GET /my-backend/audits/{audit_id} every few seconds until status is terminal. Simple, no realtime infra. Recommended default.
- Realtime push: backend broadcasts to a channel (WebSocket / SSE / Pusher / Ably / Supabase Realtime) keyed by audit_id or user_id, frontend subscribes after receiving the audit_id. Lower latency, more setup.

Do NOT have the frontend poll CiteFlow's GET /audit/{id} directly — that's what the webhook eliminates, and it would leak my API key into the browser.

## Logging
- BEFORE verifying a webhook: log X-CiteFlow-Webhook-Id and X-CiteFlow-Webhook-Timestamp on error paths. Do NOT JSON-parse the body just to log event.id — parsing before verifying defeats the security check.
- AFTER successful verify + parse: log event.id and event.type alongside any downstream-processing errors.
- For outbound calls I make (POST /audit, replay): log CiteFlow request_id from the response on errors.
- Never log CITEFLOW_API_KEY, CITEFLOW_WEBHOOK_SECRET, Authorization headers, or raw signature header values.

## Official SDKs — prefer them on both directions
- Node.js: `npm install @citeflow/sdk`. Citeflow class with .audits.create() for the outbound trigger + top-level parseWebhookEvent() / verifyWebhookSignature() for the inbound handler. .webhooks.replay(deliveryId) on the client for outbound replay.
- Python: `pip install citeflow-python`. Same surface, snake_case (audits.create(), parse_webhook_event() / verify_webhook_signature() at module level).

### SDK return shape
- Outbound SDK calls return the UNWRAPPED "data" object on success (not the { data, request_id } envelope). On failure they RAISE a CiteflowError carrying .code / .message / .requestId (Node) or .request_id (Python) / .docUrl / .status.
- parseWebhookEvent() / parse_webhook_event() verifies + JSON-parses + returns the typed event in one call. If it throws, return 400.

### Use SDK helpers, don't re-implement
The SDKs ship: auto-retry on 429+5xx with backoff + Retry-After, auto Idempotency-Key with proper reuse across SDK-internal retries, and full webhook signature verification (timestamp drift, raw body bytes, constant-time compare, rotation grace). USE THEM. Fall back to raw fetch / hand-rolled HMAC only for behaviour the SDK doesn't provide.

## What I want you to build
<<< DESCRIBE THE FULL FEATURE — for example:
"In my Next.js 14 App Router app:
- POST /api/scan accepts { url, type } from the user, fires the audit via @citeflow/sdk, stores { audit_id, url, status: 'pending', user_id } in my Postgres scans table, and returns audit_id immediately.
- POST /webhooks/citeflow verifies the signature with parseWebhookEvent, then UPSERTs the matching scans row with scores on audit.completed (or status='failed' on failures), and ACKs 200.
- The frontend SWR-fetches /api/scans/{audit_id} with a 3-second refresh until status is terminal, then renders the result card.
Include a Jest test that mocks both client.audits.create() and parseWebhookEvent()." >>>

## Constraints
- Use the SDK in BOTH directions (outbound .audits.create + inbound parseWebhookEvent) if available; otherwise raw HTTP + hand-rolled HMAC per the spec above.
- Read CITEFLOW_API_KEY and CITEFLOW_WEBHOOK_SECRET from environment. Never hardcode.
- Capture the RAW request body BEFORE any JSON parsing on the webhook route.
- Implement idempotent processing using event.id (or data.audit_id as fallback dedup key).
- Write at least one happy-path test that does NOT hit the live API and does NOT require a real HMAC signature. Mock client.audits.create() for the outbound side and parseWebhookEvent() for the inbound side.
- Include a short README: env-var setup, how to expose the webhook URL locally (e.g. ngrok / cloudflared) for testing, and a curl that simulates a scan trigger.
- When something is unspecified (DB driver, frontend bridge choice, framework details), make the smallest reasonable assumption, tag with "// ASSUMPTION:", and isolate behind a tiny adapter. Do NOT invent CiteFlow API endpoints, payload fields, event types, header names, or signing rules beyond what's listed above. You MAY create partner-owned application endpoints (e.g. POST /api/scan, GET /api/scans/{audit_id}, POST /webhooks/citeflow) — those belong to my codebase, not CiteFlow's API surface.