Base URL: https://api.rctrl.com. Authenticate with a Bearer key from
Settings → API (or one minted by rankcontrol login).
A machine-readable OpenAPI spec of every endpoint, generated from the live route table, is at rctrl.com/openapi.json.
curl -s https://api.rctrl.com/api/v1/overview/funnel \
-H "Authorization: Bearer rctrl_pk_..."Conventions
- Successful responses wrap the payload:
{ "data": ... }. - Errors return a JSON body
{ "error": "message" }with a matching HTTP status:400bad input,401bad key,403missing scope,404not yours or not found,429rate limited. POSTbodies are JSON withContent-Type: application/json.- The API evolves additively. Fields and optional arguments get added; existing ones are never renamed or repurposed.
Scopes
| Scope | Grants |
|---|---|
read:citations |
Visibility scores, trends, citation checks, sentiment, sources |
read:content |
Content pages, ideas, backlinks, social threads, brand data |
read:analytics |
Traffic, rankings, engagement, reports, jobs, crawler access |
write:content |
Plan, generate, archive, ideas, outreach drafts, brand writes, support |
write:queries |
Tracked-query management |
write:publish |
Publishing to the connected CMS |
write:backlinks |
Outreach status, Link Network membership and placements |
write:social |
Repurpose generation and pushes, social thread actions |
manage:org |
Article policy, team management |
Rate limits
Two layers apply on every request: a per-key plan limit, and a per-route cap
on costly or side-effect routes (the Cap/min column below). Exceeding
either returns 429 with a retryAfterMs hint. The caps are sized so
normal use never hits them; they exist to stop runaway loops.
The dry-run pattern
Publicly visible side effects (publishing, social pushes, outreach sends, Link Network changes, team invites) return a preview by default:
{ "data": { "dryRun": true, "note": "Repeat with confirm: true." } }Send the same request again with "confirm": true to execute. Design agent
workflows so a human sees the dry-run output before the confirm call.
Endpoints
| Endpoint | Scope | Cap/min | Purpose |
|---|---|---|---|
GET /api/v1/overview/funnel |
read:analytics | plan | AI pipeline: crawls, AI visits |
GET /api/v1/visibility/score |
read:citations | plan | Composite visibility score |
GET /api/v1/visibility/trend |
read:citations | plan | Daily visibility series |
GET /api/v1/visibility/share-of-voice |
read:citations | plan | You vs competitors |
GET /api/v1/competitors |
read:citations | plan | Tracked competitors: visibility score, 30-day citations of checks, domain metrics, positioning analysis |
GET /api/v1/visibility/web-total-history |
read:citations | plan | Monthly web total for you and each competitor, last 3 months |
GET /api/v1/visibility/sources |
read:citations | plan | Domains AI answers cite |
GET /api/v1/visibility/sentiment |
read:citations | plan | Citation framing |
GET /api/v1/citations |
read:citations | plan | Recent citation checks |
GET /api/v1/queries |
read:citations | plan | Tracked-query pool |
POST /api/v1/queries |
write:content | 10 | Add a tracked query |
GET /api/v1/crawler-access |
read:analytics | plan | AI-crawler reachability probe |
GET /api/v1/content |
read:content | plan | Content pages |
GET /api/v1/content/ideas |
read:content | 30 | Scored idea backlog |
POST /api/v1/content/ideas/plan |
write:content | 10 | Plan an idea onto the calendar |
POST /api/v1/content/ideas/hide |
write:content | 30 | Hide an idea from Content Ideas; a tracked query keeps its weekly checks and its slot |
GET /api/v1/content/optimizer |
read:content | plan | Citability report |
GET /api/v1/content/planning-capacity |
read:content | plan | Remaining plan slots |
POST /api/v1/content/plan |
write:content | 5 | Generate candidate titles |
POST /api/v1/content/plan/commit |
write:content | 10 | Commit approved titles |
POST /api/v1/content/generate |
write:content | 5 | Write a planned article now (at most 5 articles in any 24 hours) |
POST /api/v1/content/publish |
write:publish | 10 | Publish to the CMS (dry run) |
POST /api/v1/content/reschedule |
write:content | 20 | Move a planned article |
POST /api/v1/content/archive |
write:content | 30 | Archive an article |
GET /api/v1/content/internal-links |
read:content | plan | Link graph for an article |
GET /api/v1/settings/articles |
manage:org | plan | Article policy |
POST /api/v1/settings/articles |
manage:org | 10 | Patch the policy |
GET /api/v1/links/pages |
read:content | plan | Site pages for internal links |
POST /api/v1/links/pages |
write:content | 10 | Add site pages |
POST /api/v1/links/detect |
write:content | 3 | Scan a sitemap or blog root |
GET /api/v1/analytics/traffic |
read:analytics | plan | Traffic overview (null until Analytics is activated) |
GET /api/v1/analytics/rankings |
read:analytics | plan | Google and Bing positions per keyword, Search Console clicks and impressions, and whether Google’s AI Overview shows and names your page. ?scope=ours|site |
GET /api/v1/analytics/engagement |
read:analytics | 30 | Per-page views and citations |
GET /api/v1/analytics/sources |
read:analytics | plan | Source selections, qualified options, install state |
POST /api/v1/analytics/sources |
manage:org | 10 | Select the writer for a data type |
POST /api/v1/analytics/activate |
manage:org | 10 | Turn on the Analytics or Reports screen |
POST /api/v1/integrations/cloudflare/connect-url |
manage:org | 10 | Cloudflare OAuth URL (crawler data source) |
GET /api/v1/integrations/cloudflare/zones |
manage:org | 10 | Zones visible to the grant |
POST /api/v1/integrations/cloudflare/zone |
manage:org | 10 | Pick the polled zone, start first sync |
POST /api/v1/integrations/framer/install-embed |
manage:org | 5 | Site-wide tracking on Framer (dry run; confirm publishes their site) |
POST /api/v1/integrations/webflow/custom-code |
manage:org | 5 | Tracking loader via Webflow custom code (dry run) |
GET /api/v1/reports/summary |
read:analytics | 30 | Executive summary (null until Reports is activated) |
GET /api/v1/reports/wins |
read:analytics | 30 | Top wins (null until Reports is activated) |
GET /api/v1/reports/agent-activity |
read:analytics | 60 | Runs per agent lane |
GET /api/v1/jobs |
read:analytics | plan | Recent agent runs |
GET /api/v1/repurpose |
read:content | plan | Repurpose queue or drafts |
GET /api/v1/repurpose/channels |
write:social | 3 | Buffer and Postiz channels, each tagged with its scheduler |
POST /api/v1/repurpose/generate |
write:social | 5 | Draft social posts (dry run) |
POST /api/v1/repurpose/draft |
write:social | plan | Edit a draft |
POST /api/v1/repurpose/push |
write:social | 5 | Push to Buffer or Postiz (dry run; scheduler needed when both are connected) |
POST /api/v1/repurpose/mark-posted |
write:social | plan | Mark posted |
GET /api/v1/backlinks |
read:content | 60 | Backlink table |
GET /api/v1/backlinks/stats |
read:content | 60 | Backlink and pipeline stats |
GET /api/v1/outreach/prospects |
read:content | plan | Outreach pipeline; each row carries dr and drSource (ahrefs, or dataforseo for an estimate) |
GET /api/v1/outreach/stats |
read:content | 60 | Outreach funnel for the last 90 days by prospect method (intersection, footprint, mention, fresh, brand_mention, legacy): prospects, sent, replied, placed, rates per send, plus the total |
POST /api/v1/outreach/find-contact |
write:content | 5 | Find a prospect contact |
POST /api/v1/outreach/draft-reply |
write:content | 5 | AI-draft a reply |
POST /api/v1/outreach/queue |
write:content | 10 | Queue a send (dry run) |
POST /api/v1/outreach/status |
write:backlinks | 30 | Move a prospect |
GET /api/v1/link-network |
read:content | 30 | Credits, membership, placements |
POST /api/v1/link-network/opt-in |
write:backlinks | 5 | Join or leave (dry run) |
POST /api/v1/link-network/remove-placement |
write:backlinks | 10 | Retire a placement (dry run) |
GET /api/v1/social |
read:content | 30 | Social thread prospects |
GET /api/v1/social/stats |
read:content | 60 | Thread pipeline counts |
POST /api/v1/social/status |
write:social | 30 | Move a thread |
POST /api/v1/social/draft-reply |
write:social | 5 | AI-draft a reply |
POST /api/v1/social/open |
write:social | 30 | Open a drafted thread to post yourself; returns the thread URL (X: a composer link with the reply filled in) and starts the checks that mark it Posted |
POST /api/v1/social/x-handle |
write:social | 10 | Save the optional X handle used to recognise posted replies (empty clears) |
POST /api/v1/social/reddit-profile |
write:social | 10 | Save the Reddit account the Social tab drafts for: username (optional), karma, accountAge (under1mo, 1to6mo, 6moto2yr, over2yr), goal, founderStory, tone. Replaces the stored profile; returns the readiness tier |
GET /api/v1/topics |
read:content | plan | The pillar list (topic clusters) |
POST /api/v1/topics |
write:content | 10 | Replace the full pillar list; up to 20 topics |
GET /api/v1/brand |
read:content | 60 | Brand profile, products, ICPs |
POST /api/v1/brand |
write:content | 20 | Patch identity: name, industry, productDescription, authors, styleReferenceUrls, brandAliases (other spellings searched as brand mentions), brandExclusions (same-name brands skipped). Arrays replace the stored list |
POST /api/v1/brand/profile |
write:content | 20 | Patch voice and style |
POST /api/v1/brand/product |
write:content | 20 | Upsert or delete a product |
POST /api/v1/brand/icp |
write:content | 20 | Upsert or delete a buyer profile |
POST /api/v1/brand/icp/suggest |
write:content | 10 | Up to 8 audiences for this site from its brand, products, competitors and topics. Saves nothing. Body: exclude (titles already shown) |
POST /api/v1/brand/icp/draft |
write:content | 10 | One buyer profile drafted from describe (a sentence), suggestion ({title, who}), or given fields, which are kept as written. Returns fields to review; save with /brand/icp |
GET /api/v1/team |
manage:org | plan | Members and invites |
POST /api/v1/team/invite |
manage:org | 5 | Invite (dry run) |
POST /api/v1/team/revoke |
manage:org | plan | Revoke an invite |
POST /api/v1/team/remove |
manage:org | 5 | Remove a member (confirm) |
POST /api/v1/support |
write:content | 3 | File a support message |
GET /api/v1/articles |
read:content | plan | Content API for headless sites |