---
title: "REST API"
description: "The HTTP API behind the CLI and MCP server, with scopes, rate limits, and the dry-run pattern."
---

> Documentation Index
> Fetch the complete documentation index at: https://rctrl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

Base URL: `https://api.rctrl.com`. Authenticate with a Bearer key from
**Settings → API** (or one minted by `rankcontrol login`).

```sh
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, ideas, backlinks, social threads, brand data |
| `read:leads` | Captured leads |
| `read:analytics` | Traffic, 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:

```json
{ "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, AI leads |
| `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/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 |
| `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 |
| `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/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/leads` | read:leads | plan | Captured leads |
| `GET /api/v1/repurpose` | read:content | plan | Repurpose queue or drafts |
| `GET /api/v1/repurpose/channels` | write:social | 3 | Postiz channels |
| `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 Postiz (dry run) |
| `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 |
| `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 |
| `GET /api/v1/brand` | read:content | 60 | Brand profile, products, ICPs |
| `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 |
| `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 |

> **Note**
>
> `GET /api/v1/articles` is the headless Content API used by Next.js and
> static-site destinations. Connect one in **Brand Control → Publishing** and
> the dashboard hands you copy-paste routes for it.

Source: https://rctrl.com/api/index.mdx