Skip to content
rctrl Docsrctrl Docs

REST API

The HTTP API behind the CLI and MCP server, with scopes, rate limits, and the dry-run pattern.

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: 400 bad input, 401 bad key, 403 missing scope, 404 not yours or not found, 429 rate limited.
  • POST bodies are JSON with Content-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, backlinks, social threads, brand data
read:analytics Traffic, rankings, Google vs AI, engagement, reports, jobs, crawler access
write:content Plan, generate, archive, tracked queries, brand writes, support
write:publish Publishing to the connected CMS
write:backlinks Outreach contacts, reply drafts, sends and status
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 field and a Retry-After header (seconds). 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, 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, and recording a reply you posted or a contact form you sent (social/threads/posted, outreach/form-sent) never waits. 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/overview/movers read:citations 30 Tracked queries whose citation rate moved most this week.
GET /api/v1/visibility/score read:citations plan Composite visibility score. lastChecked is the newest check’s day when it is over 8 days old, else null.
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: other names and sites, visibility score, 30-day citations of checks, 30-day win rate, domain metrics, positioning analysis. you holds your own win rate
POST /api/v1/competitors/update write:content 10 Set a competitor’s other names (aliases) and sites (extraSites); each list sent replaces the stored one. Removing one waits for the owner
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/pages read:citations plan The pages AI answers cite, in top, new and losing lists, each with its type, whose site it is and its answers in the last 4 weekly checks and the 4 before
GET /api/v1/visibility/sentiment read:citations plan Citation framing
GET /api/v1/citations read:citations plan Recent citation checks, newest first. ChatGPT and Grok rows carry the engine’s searches, each with targetedBy when one of your articles targets it. before (ISO date or milliseconds) pages back; a full page returns nextBefore. branded marks a check of a question that names your brand. A row whose answer contradicts one of your facts carries contradiction: the fact, the answer’s sentence and the words that state the claim.
GET /api/v1/queries read:citations plan List the tracked queries, each with how many of the AI engines that answered it cited it in their latest check; noAnswer names an engine with no answer (Google shows an AI Overview for some questions only); branded marks a question that names your brand, which doesn’t count toward your score
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. status keeps one status, limit (1 to 200) sets the page size, before (ISO date or milliseconds) pages back; a full page returns nextBefore.
GET /api/v1/opportunities read:content 60 Action Items: what to work on next on your site (product and service pages, searches no page is about, searches your pages and articles show in Google’s top 10 for with no clicks, problems across the whole site, and AI answers that contradict one of your facts), each item with its group (stops, costs or polish), its evidence lines and the numbers behind them, a suggested fix and its action
POST /api/v1/opportunities/hide write:content 30 Hide an action item; it moves under Done as Hidden and does not come back
POST /api/v1/opportunities/move write:content 30 Save a search no page is about for Plan Content, 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 action 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 The next batch of titles (dry run), or titles about a subject
GET /api/v1/content/plan/batch read:content plan The next batch of titles
POST /api/v1/content/plan/batch write:content 10 Add the next batch, or its titles in keep (dry run)
POST /api/v1/content/plan/news write:content 10 This week’s news titles (dry run), or add them with confirm
POST /api/v1/content/plan/batch/remove write:content 30 Remove a title from the next batch or this week’s news for good (waits for the owner)
POST /api/v1/content/plan/commit write:content 10 Add reviewed titles from a planning run (runId)
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
POST /api/v1/content/restore write:content 10 Restore an archived article; putting it back on the site also needs write:publish (dry run)
GET /api/v1/content/internal-links read:content plan Link graph for an article
GET /api/v1/content/impact read:citations plan An article’s questions in AI answers, the 4 weeks before it went live against every answer since (?contentId=)
GET /api/v1/content/by-url read:content 60 Your published article at an address (?url=): contentId, title, the citabilityScore the dashboard shows and dashboardUrl, or null
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, with scroll depth and the change from the period before (null until Analytics is activated). ?scope=site: the whole site from Google Analytics (visits, from search, from AI by engine, trend, top pages, and aiConversions: AI key events, key event rate, revenue and AI landing pages when Google Analytics tracks key events), or a hint when it is not connected
GET /api/v1/analytics/traffic-trend read:analytics 30 Visits to your articles over time. ?days=7|30|90. Null until Analytics is activated.
GET /api/v1/analytics/traffic-pages read:analytics 30 Visits to each of your articles. ?days=7|30|90. Null until Analytics is activated.
GET /api/v1/analytics/traffic-sources read:analytics 30 Where visits to your articles came from. ?days=7|30|90. Null until Analytics is activated.
GET /api/v1/analytics/search-console read:analytics 30 Search Console totals and daily clicks and impressions. ?days=7|30|90. Null until Analytics is activated, and while Search Console is not connected.
GET /api/v1/analytics/search-console-queries read:analytics 30 Top Search Console searches by clicks. ?days=7|30|90. Null until Analytics is activated, and while Search Console is not connected.
GET /api/v1/analytics/search-console-trend read:analytics 30 Search Console clicks and impressions by day. ?days=7|30|90. Null until Analytics is activated, and while Search Console 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/movers read:analytics 30 Biggest Google position changes in the last 30 days. ?scope=ours|site. Null until Analytics is activated.
GET /api/v1/analytics/google-vs-ai read:analytics 30 Every tracked question: its place in Google’s top 30 beside each AI engine’s latest check (cited, mentioned or none), and the row’s state.
GET /api/v1/analytics/ai-crawling read:analytics 30 AI crawler visits: the total, each crawler’s visits with the busiest first, and each day’s visits per crawler. ?days=7|30|90. Null until Analytics is activated, and while no AI crawler source is selected
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); aiKeyEvents and aiRevenue when Google Analytics tracks key events
GET /api/v1/reports/wins read:analytics 30 Top wins (null until Reports is activated); the best new backlink leaves out links hidden as spam
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; each row carries dr and drSource (whether the rating is measured or estimated), and spamScore (0 to 100) when the weekly check has one. A link the Link Profile hides as spam carries spamKind: ad for a link ad, auto for an auto-generated page
GET /api/v1/backlinks/stats read:content 60 Backlink and pipeline stats. The outreach counts are your article prospects’; aiSources holds the same counts for AI sources. The spam the Link Profile hides is counted in spam and left out of backlinksShown, referringDomainsShown, lostShown and avgDR; checks lists the last 12 weekly checks
GET /api/v1/outreach/prospects read:content plan Outreach pipeline; each row carries dr and drSource (whether the rating is measured or estimated), the prospect’s next step (nextMove), its stage, hasDraft (whether an email is drafted) and autopilotHeld (whether Autopilot held that email for your review), competitor (a site of a business that sells what you sell), contactPageUrl (their contact page, when the lookup read one), outreachChannel (email or form) and formSentAt. ?aiSources=true lists only AI sources: pages AI engines cite for your tracked questions, each with the product or service it offers (aiSource). Needs a product or service in Brand Kit
GET /api/v1/outreach/stats read:content 60 Outreach funnel for the last 90 days by prospect method (intersection, footprint, mention, fresh, brand_mention, ai_source, legacy): prospects, sent, replied, placed, rates per send, plus the total, and aiSources (found this billing window, cap, resetsAt)
POST /api/v1/outreach/find-contact write:backlinks 5 Find a prospect contact
POST /api/v1/outreach/draft-reply write:backlinks 5 AI-draft a reply
POST /api/v1/outreach/draft-email write:backlinks 5 The first email to a prospect: its saved draft, or a new AI draft saved on it. Nothing sends
POST /api/v1/outreach/form-fill write:backlinks 5 What to type into a prospect’s contact form when no email was found (prospectId): name, email (with emailNote when it is your own address), subject, message and contactPageUrl; followUp is true once its one follow-up opens. The first message is the saved draft, or a new AI draft saved on it. Nothing sends
POST /api/v1/outreach/form-sent write:backlinks 20 Record a message you sent through a prospect’s contact form (prospectId, pageUrl): the first one moves it to Contacted, and followUpAt says when its one follow-up opens. Counts toward the outreach daily limit (dry run)
POST /api/v1/outreach/queue write:backlinks 10 Queue a send (dry run)
POST /api/v1/outreach/cancel write:backlinks 10 Cancel a queued outreach email before it sends. Refused once it has gone out
POST /api/v1/outreach/status write:backlinks 30 Move a prospect
POST /api/v1/outreach/ai-source-product write:backlinks 30 Change the product or service an AI source offers, until its pitch is queued
GET /api/v1/social read:content 30 Social thread prospects; each thread carries its next step (nextMove) and stage. ?stage= lists one stage (identified, reply_ready, opened, posted or skipped), as the Social tab’s chips do. ?aiSources=true lists only the threads AI engines cite for your tracked questions (aiCited). Needs a product or service in Brand Kit
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/threads/posted write:social 20 Record the reply you posted on a thread you opened (threadId, permalink, postedText); the thread moves to Posted. On Reddit the link must be a comment on that thread; on X, your reply’s own post (dry run)
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), each with how many tracked questions it holds; none counts the questions with no topic. Each topic also carries published and planned (its articles live, and planned or drafted); the answer adds the workspace’s published, planned, thin (topics with fewer than 5 published) and orphans (published articles no other published article links to).
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, buyers, 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
GET /api/v1/objections read:content 60 The objections AI raises about you, as Buyer Profiles shows them: each with its words (text), answers in the last 30 days and engines; the ones 2 or more answers raised, most answers first
POST /api/v1/objections/accept write:content 20 Add one to a buyer profile: first in its objections. Body: suggestionId, profileId, optional text (your own words)
POST /api/v1/objections/dismiss write:content 30 Dismiss one; it isn’t suggested again. Waits for the owner. Body: suggestionId
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/brand/facts read:content 30 The facts AI’s answers are checked against: each fact’s type, the product a seeded fact follows, the open action item when an answer contradicts it, and the contradictions of the last 30 days (contradictions)
POST /api/v1/brand/facts write:content 20 Add a fact: type (price, plan, integration, guarantee or other) and text, one sentence
POST /api/v1/brand/facts/update write:content 20 Edit a fact’s text or type (factId). Editing a seeded fact stops it following its product
POST /api/v1/brand/facts/delete write:content 20 Delete a fact (waits for the owner)
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 our IP, the API, CLI and MCP, and the plan and pricing; without a page, the list of pages
GET /api/v1/guides read:content 30 The guides on RankControl’s blog that best answer a question, with ?q=<question>: each guide’s title, date, link and the section that answers
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

The visibility score, trend, share of voice, sources, pages and sentiment, GET /api/v1/queries, GET /api/v1/citations and GET /api/v1/competitors take ?topic=: a topic’s id or name from GET /api/v1/topics, or none for the questions with no topic. Leave it out for the whole workspace. They also take ?engines=: engine ids, comma-separated (chatgpt,claude), to count only those engines’ answers. Leave it out for all seven.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close