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, Editorial Circle 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
Side effects with a cost or a public face (writing articles, publishing, social pushes, outreach sends, Editorial Circle changes, team invites) return a preview by default:
{ "data": { "dryRun": true, "note": "Repeat with confirm: true." } }Send the same request with "confirm": true to execute. An agent acting
on the user’s request can send confirm: true the first time.
Changes that wait for the owner
Removing, archiving, hiding, replacing a list and team changes always wait
for the workspace owner. So does every change a key or app asks for in the
2 hours after it reads text written outside the workspace: prospect
replies, AI answers, social threads, competitor pages. In those 2 hours,
contact lookups wait only if the outreach mailbox has Autopilot on. A
request that waits answers 202:
{ "data": { "status": "approval_required", "approvalId": "...", "approveUrl": "https://rctrl.com/dashboard/approvals/..." } }Nothing changes until the owner approves in RankControl.
GET /api/v1/approvals?id= shows where the request stands and what each
change returned. Sending the same request again returns that approval, not
a new one. While it waits, the answer is the same 202. For an hour after
the owner approves, it is 200 with "status": "already_approved" and the
result, and nothing runs twice. Approving happens only in the dashboard.
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, newest first. before (ISO date or milliseconds) pages back; a full page returns nextBefore |
GET /api/v1/queries |
read:citations | plan | List the tracked queries, each with how many of the 6 AI engines cited it in their latest check |
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/opportunities |
read:content | 60 | Insights: what to work on next on your site (product and service pages, searches no page is about, problems across the whole site), each item with its evidence lines, a suggested fix and its action |
POST /api/v1/opportunities/hide |
write:content | 30 | Hide an Insights item; it moves under Done as Hidden and does not come back |
POST /api/v1/opportunities/move |
write:content | 30 | Move an Insights search no page is about to Content Ideas, tagged Search Console; the item moves under Done |
POST /api/v1/opportunities/plan |
write:content | 5 | Plan up to 3 articles that link to an Insights item’s page (dry run) |
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, optionally about a subject |
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/write-run |
write:content | 5 | Write the next planned articles one after another, publishing each with publish: true (needs write:publish; dry run) |
GET /api/v1/content/write-runs |
read:content | plan | Recent write runs and each article’s state |
POST /api/v1/content/write-run/stop |
write:content | 10 | Stop a write run |
GET /api/v1/approvals |
read:content | plan | Where a change waiting for the owner stands (?id=) |
POST /api/v1/content/publish |
write:publish | 10 | Publish to the CMS (dry run) |
POST /api/v1/content/meta |
write:content | 20 | Change a written article’s title, meta title or meta description (dry run) |
POST /api/v1/content/reschedule |
write:content | 20 | Move a planned article |
POST /api/v1/content/settings |
write:content | 30 | Change a planned article’s own settings |
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). ?scope=site: the whole site from Google Analytics (visits, from search, from AI by engine, trend, top pages), or a hint when it is not connected |
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, brand guidelines |
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, and the Local business switch (localBusiness, serviceArea) |
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 |
POST /api/v1/brand/reviewed |
write:content | 10 | Mark the brand as reviewed |
POST /api/v1/brand/guidelines |
write:content | 20 | Add a brand guideline |
POST /api/v1/brand/guidelines/active |
write:content | 20 | Turn a brand guideline on or off |
POST /api/v1/brand/guidelines/remove |
write:content | 20 | Delete a brand guideline |
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/help |
read:content | 30 | A help page with ?page=<slug>: setup guides for each publishing destination, the crawler and its IP, the API, CLI and MCP, and the plan and pricing; without a page, the list of pages |
GET /api/v1/billing |
manage:org | 10 | Billing as Settings, Billing shows it: status, billing cycle, next charge, add-ons, usage and recent payments (read-only) |
GET /api/v1/articles |
read:content | plan | Content API for headless sites |