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, 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.