RankFlow docs

Getting started

From signup to your first AI recommendation in five steps. The whole flow runs inside our onboarding wizard at /onboarding, but here's what happens at each step so you know what to expect.

API reference

RankFlow exposes a JSON REST API for the data you've collected. Base URL: https://rankflow.my/api/v1.

Authentication

All endpoints require a bearer token. Generate one from Settings → API. Tokens look like rf_live_… (production) or rf_test_… (sandbox).

curl https://rankflow.my/api/v1/projects \
  -H "Authorization: Bearer rf_live_..."

Response envelope

Every response is wrapped in { "data": …, "meta": … }. The meta block carries the live quota numbers and a server timestamp:

{
  "data": [...],
  "meta": {
    "api_calls_today": 142,
    "api_calls_limit": 1000,
    "timestamp": "2026-05-11T14:00:00+08:00"
  }
}

Scopes

Tokens carry granular scopes. Required scope is listed per endpoint below.

• read:projects — list + view sites
• read:rankings — read rank tracking data
• read:audit — read audit results
• read:keywords — read keyword research data
• write:audit — trigger new audits

Endpoints

Rate limits

Per-plan daily caps on bearer tokens:

• Starter — no API access (upgrade to Pro)
• Pro — 1,000 calls/day
• Agency — 10,000 calls/day

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers. When you exceed the cap you'll get 429 Too Many Requests with a reset_at timestamp in the body.

Webhooks

Register HTTPS endpoints at Settings → Webhooks to receive real-time POST requests when key events fire.

Available events

• audit.completed — a crawl finished and AI summary is ready
• ranking.changed — a tracked keyword moved ≥3 positions
• backlinks.updated — daily sync new/lost counts
• report.generated — a scheduled or one-off report finished

Payload + headers

POST https://your.app/webhook
Content-Type: application/json
X-RankFlow-Event: audit.completed
X-RankFlow-Signature: 8f2c9... (HMAC-SHA256 of the raw body)
X-RankFlow-Delivery: 019e... (unique per attempt)

{
  "event": "audit.completed",
  "timestamp": "2026-05-11T14:00:00+08:00",
  "data": { "batch_id": "...", "site_id": "...", "domain": "...", "health_score": 78 }
}

Verifying signatures

Always verify the X-RankFlow-Signature header to confirm the request is from us. The signature is the HMAC-SHA256 of the raw request body using your webhook secret. Constant-time comparison only:

// Node.js
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-rankflow-signature']));

Non-2xx responses trigger 2 retries with exponential backoff (10s, 30s, 90s) — 3 attempts total.

FAQ

Support