Agent API reference

The agent API is the REST API behind agent access. It covers everything the dashboard does, for every site on the account. This page lists every endpoint with its parameters, an example request and an example response. Read Conventions first; the rest is reference.

Conventions

Base URL and versioning

All endpoints live under one base URL:

https://rankbox.xyz/api/agent/v1

The version is in the path. Within v1, Rankbox only adds things: new endpoints, new optional request fields, new response fields and new event types. Removing or renaming a field, or changing its meaning, would come as v2 at a new path. Write clients that ignore fields they don't know.

Authentication

Send an agent key or an OAuth access token in the Authorization header:

Authorization: Bearer rv_agent_xxxxxxxxxxxx

Only POST /accounts works without it. Every credential has full access to the account; there are no scopes. See Agent authentication.

Requests

• Bodies are JSON with Content-Type: application/json, at most 1 MB.
• Field names are snake_case.
• IDs are UUIDs, for example 6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64, except integration IDs, which are names such as webflow.
• A site is addressed in the path: /sites/{site_id}/…. Get site IDs from GET /sites. The primary site's ID is also account.primary_site_id.
• PATCH changes only the fields you send. Send null to clear a nullable field.
• A resource on another account returns 404 not_found, never 403, so a probe learns nothing.

Responses

• One object comes wrapped in its name: { "article": { … } }.
• A list comes as a plural name plus a cursor: { "articles": [ … ], "next_cursor": "…" }.
• Every response carries an X-Request-Id header. Quote it when you contact support.
• Timestamps are ISO 8601 in UTC, for example 2026-10-02T14:03:11Z. Calendar days such as scheduled_date are YYYY-MM-DD.
• Money is a number in US dollars, for example 49.5 for $49.50, with "currency": "usd".

Pagination

List endpoints take limit (1 to 100, default 50) and cursor. When next_cursor is null there is nothing more. Otherwise pass it back as ?cursor= to get the next page. Cursors are opaque strings; don't build or parse them.

curl "https://rankbox.xyz/api/agent/v1/sites/$SITE_ID/articles?limit=100&cursor=eyJ1IjoiMjAyNi0xMC0wMlQx…" \
  -H "Authorization: Bearer $RANKBOX_AGENT_KEY"

Idempotency

Every POST accepts an Idempotency-Key header: any string up to 255 characters, unique per operation. A UUID is a good choice.

Send one on every POST that spends credits or money: generate, POST /sites, POST /sites/{site_id}/restore, POST /billing/activate, Reddit drafts. PATCH and DELETE are naturally idempotent.

Asynchronous jobs

Work that can take longer than 30 seconds runs as a job: the site scan, research, article generation, integration syncs and Reddit sweeps. These endpoints return 202 Accepted with { "job": { … } }. Poll Get a job with ?wait=30, or listen for the matching event. Everything else answers synchronously.

Errors

Errors use the same envelope as the public API: a sentence for people and a stable code for programs.

{
  "error": "This site has used all 7 article credits for this period. They reset on 9 October 2026.",
  "code": "insufficient_credits"
}

Some errors add fields: details (an array of { "field", "problem" } on validation_failed), action_url (a page for the owner on human_required and payment_failed) and docs_url.

Rate limit headers

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) for the account's request budget. A 429 adds Retry-After in seconds. The numbers are in Billing, credits and limits.

Endpoint index

Paths are relative to https://rankbox.xyz/api/agent/v1. "Needs" is what the account must have; everything else works on an account with no plan.

Accounts

Create an account

POST /accounts

Creates an account, its primary site and an agent key, starts the site scan and emails the owner. No authentication. Full details, limits and the claim flow are in Create an account as an agent.

Returns 201 with account, site, scan_job_id, agent_key (with the secret key, shown once) and claim_url. The full example is in The response. Errors: 409 account_exists, 422 validation_failed, 429 rate_limited.

The account object

Get the account

GET /account

{
  "account": {
    "id": "8b0d3c4e-2f6a-4f1b-9d3e-5a7c1e2b9f40",
    "email": "maya@northwind.example",
    "claimed": true,
    "claimed_at": "2026-10-02T16:10:27Z",
    "created_at": "2026-10-02T14:03:11Z",
    "created_by_agent": {
      "name": "Atlas",
      "operator": "Northwind Analytics",
      "contact_url": "https://northwind.example/atlas"
    },
    "primary_site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "billing_status": "trialing"
  }
}

A cheap call: use it to check a credential.

Resend the claim email

POST /account/resend-claim

Sends the owner a new claim email and returns the new link. At most 3 a day per account.

{ "sent": true, "claim_url": "https://rankbox.xyz/claim/ct_xxxxxxxxxxxx" }

Errors: 409 conflict when the account is already claimed, 429 rate_limited after 3 in a day.

Delete the account

DELETE /account

Deleting the account removes every site, article and setting and can't be undone, so only the signed-in owner can do it, from Dashboard → Settings → Account. The agent API always answers:

{
  "error": "Only the account owner can delete the account, from Dashboard → Settings → Account.",
  "code": "human_required",
  "action_url": "https://rankbox.xyz/dashboard/settings"
}

Agent keys

The agent key object

List agent keys and connections

GET /agent-keys

{
  "agent_keys": [
    {
      "id": "2d4f6a8c-1e3b-4c5d-8f7a-9b0c1d2e3f45",
      "type": "key",
      "name": "Atlas",
      "prefix": "rv_agent_a1b2c3…",
      "client_id": null,
      "operator": "Northwind Analytics",
      "contact_url": "https://northwind.example/atlas",
      "created_at": "2026-10-02T14:03:11Z",
      "last_used_at": "2026-10-02T15:22:05Z"
    },
    {
      "id": "b8d0f2a4-6c8e-4a1b-9c3d-5e7f9a1b3c86",
      "type": "oauth",
      "name": "Claude",
      "prefix": null,
      "client_id": "c3f1e5d7-…",
      "operator": null,
      "contact_url": null,
      "created_at": "2026-10-04T08:31:50Z",
      "last_used_at": "2026-10-04T08:35:12Z"
    }
  ],
  "next_cursor": null
}

Revoked keys and disconnected apps aren't listed.

Create an agent key

POST /agent-keys

Returns 201 with { "agent_key": { … "key": "rv_agent_xxxxxxxxxxxx" … } }. The owner is emailed. At most 25 active keys and connections per account; beyond that, 409 conflict. Example in Create a key through the API.

Revoke a key or connection

DELETE /agent-keys/{id}

Revokes an agent key or disconnects an OAuth app, immediately. Webhook endpoints it registered are disabled. Returns { "revoked": true, "id": "…" }. You can revoke the key you are calling with; the next request then returns 401.

Activity

List activity

GET /activity

The activity log the owner sees at Dashboard → Settings → Agent access: every change made by an agent or by the owner, newest first, kept for 365 days.

{
  "activity": [
    {
      "id": "d1e3f5a7-9b2c-4d6e-8f0a-2b4c6d8e0f13",
      "created_at": "2026-10-02T15:22:05Z",
      "actor": { "type": "agent", "id": "2d4f6a8c-1e3b-4c5d-8f7a-9b0c1d2e3f45", "name": "Atlas" },
      "action": "article.generate",
      "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
      "resource": { "type": "article", "id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76" },
      "summary": "Started writing “How to choose a product analytics tool for B2B SaaS” (1 article credit)",
      "ip": "203.0.113.7"
    }
  ],
  "next_cursor": null
}

actor.type is agent (a key), app (an OAuth connection), owner or rankbox (autopilot and other scheduled work).

Sites

The site object

A site is usable when status is active and removes_at is null or in the future.

List sites

GET /sites

Returns every site on the account, primary first, then Studio sites in the order they were added, archived ones included.

{
  "sites": [
    {
      "id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
      "kind": "primary",
      "status": "active",
      "brand_name": "Northwind Analytics",
      "website_url": "https://northwind.example",
      "product_description": "Product analytics for B2B SaaS teams: funnels, retention and feature adoption without SQL.",
      "avatar_url": "https://northwind.example/apple-touch-icon.png",
      "writing": {
        "tone": "Confident",
        "writing_style": "In-depth and data-driven",
        "audience": "Product managers at B2B SaaS companies",
        "brand_voice": "Say \"teams\", not \"users\".\nNever name competitors.\nUse US spelling."
      },
      "scan_status": "completed",
      "billed_from": null,
      "removes_at": null,
      "archived_at": null,
      "dashboard_url": "https://rankbox.xyz/dashboard?site=6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
      "created_at": "2026-10-02T14:03:11Z"
    }
  ],
  "next_cursor": null
}

Get a site

GET /sites/{site_id}

Returns { "site": { … } } in the shape above.

Update a site

PATCH /sites/{site_id}

PATCH /sites/6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64
Content-Type: application/json

{ "writing": { "tone": "Confident", "audience": "Product managers at B2B SaaS companies" } }

Returns the updated { "site": { … } }. The writing settings feed every article written afterwards, by you or autopilot. See Brand voice and writing settings.

Add a Studio site

POST /sites

Adds a Studio site: an extra site with its own plan allowance, billed at $49.50 a month on the same subscription. Rankbox charges the card on file at once for the rest of the current period (prorated), and only a successful charge creates the site. The scan then starts as it did for the first site. Needs a paid plan; check Get a Studio quote first. Send an Idempotency-Key.

{
  "site": {
    "id": "a3e9b1c7-5d2f-4c8a-9e6b-7f1a2d3c4b58",
    "kind": "studio",
    "status": "active",
    "brand_name": "Fernhill Coffee",
    "website_url": "https://fernhill.example",
    "product_description": "",
    "avatar_url": null,
    "writing": { "tone": "Professional", "writing_style": "Balanced", "audience": "Founders / Entrepreneurs", "brand_voice": "" },
    "scan_status": "running",
    "billed_from": "2026-10-20T10:00:00Z",
    "removes_at": null,
    "archived_at": null,
    "dashboard_url": "https://rankbox.xyz/dashboard?site=a3e9b1c7-5d2f-4c8a-9e6b-7f1a2d3c4b58",
    "created_at": "2026-10-20T10:00:00Z"
  },
  "scan_job_id": "4d6f8a0c-2e4b-4c6d-8e0f-1a3b5c7d9e21",
  "charged": { "amount": 24.75, "currency": "usd" }
}

Errors: 402 paid_plan_required during the trial or without a plan (see End the trial now), 402 payment_failed when the card is declined (no site is created), 403 human_required when the bank asks the cardholder to authenticate, 409 conflict while another site change on the account is in progress (retry after a few seconds).

Remove a Studio site

DELETE /sites/{site_id}

Schedules a Studio site's removal at the end of the period already paid for. Nothing is refunded and nothing is deleted: the site keeps working until removes_at, then becomes archived, and its articles stay readable. The primary site can't be removed; the call returns 409 conflict (cancel the plan in the billing portal instead).

{ "site": { "id": "a3e9b1c7-5d2f-4c8a-9e6b-7f1a2d3c4b58", "kind": "studio", "status": "active", "removes_at": "2026-11-17T15:20:44Z" } }

The response holds the full site object; it is shortened here.

Restore a Studio site

POST /sites/{site_id}/restore

Undoes a removal. If the site is still running with a removes_at in the future, this cancels the removal at no cost. If the site is archived, Rankbox charges the prorated price for the rest of the period, like adding a site, and brings it back with its articles. Body: optional proration_date from a quote. Returns { "site": { … }, "charged": null } or with charged set. Same errors as Add a Studio site.

Get the scan

GET /sites/{site_id}/scan

The latest scan of the site's website: brand, analysis and the articles it added to the plan.

{
  "scan": {
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "job_id": "3c5e7a9b-1d3f-4b5c-8e7a-9c1b3d5f7a92",
    "status": "completed",
    "stage": "plan",
    "started_at": "2026-10-02T14:03:12Z",
    "finished_at": "2026-10-02T14:05:40Z",
    "brand": {
      "brand_name": "Northwind Analytics",
      "product_description": "Product analytics for B2B SaaS teams: funnels, retention and feature adoption without SQL.",
      "avatar_url": "https://northwind.example/apple-touch-icon.png"
    },
    "analysis": {
      "niche": "B2B product analytics",
      "audience": "Product managers and founders at B2B SaaS companies",
      "geo": "United States",
      "competitors": ["Lumen Metrics", "Quarry"]
    },
    "keywords_found": 20,
    "articles_planned": 20,
    "ideas": 4,
    "scheduled": 16,
    "error": null
  }
}

stage is brand, analysis or plan. Fields the scan couldn't ground in the website come back empty rather than guessed.

Run the scan again

POST /sites/{site_id}/scan

Re-scans the website and rebuilds the plan from it. Returns 202 with a site.scan job. What it changes:

• Brand fields that are empty are filled in; fields you set are kept.
• Keywords it finds replace keywords with the same name; others are kept.
• Unwritten articles (opportunity or scheduled, empty body) for the same keywords are replaced; written articles are never touched.

On an account with no trial or plan, at most 3 scans a day, the first one included.

Research and keywords

Run research

POST /sites/{site_id}/research

Finds keywords buyers search for and article ideas for the site, using its brand and writing settings. Free; counts toward the AI rate limit. Returns 202 with a research job.

The finished job's result:

{
  "keywords": [
    { "name": "feature adoption metrics", "tag": "High Intent", "search_volume": 1300, "traffic_estimate": 230, "intent": "Informational", "trend": "Rising" }
  ],
  "ideas": [
    { "title": "Feature adoption metrics: the 6 that predict expansion revenue", "description": "Define each metric, show how to compute it, and when it matters.", "keyword": "feature adoption metrics", "traffic_estimate": 900, "competition": "Low", "ai_signal": 84 }
  ],
  "saved": { "keywords": 18, "articles": 10 }
}

Up to 24 keywords per run. search_volume, traffic_estimate, competition and ai_signal are model estimates for planning, not measured data. saved is null when save is false. On an account with no trial or plan, at most 10 research runs a day. See Research.

The keyword object

List keywords

GET /sites/{site_id}/keywords?source=library

source is optional. Returns { "keywords": [ … ], "next_cursor": null }, highest search_volume first.

Add a keyword

POST /sites/{site_id}/keywords
Content-Type: application/json

{ "name": "product analytics for startups", "intent": "Commercial", "search_volume": 880 }

Returns 201 with { "keyword": { … "source": "library" … } }. A keyword with the same name on the site returns 409 conflict. Tracked keywords drive Get Rank.

Delete a keyword

DELETE /sites/{site_id}/keywords/{keyword_id}

Returns { "deleted": true, "id": "…" }. Articles that target the keyword are kept.

Articles

The article object

The writer's notes in body are image ideas written as **[Image: …] (alt: "…")** and internal-link suggestions written as [anchor](#internal: target). Destinations never receive them: body_markdown and body_html drop the image ideas and keep only the anchor text of internal-link suggestions. An agent that builds the website can use them to add images and real internal links. The body usually starts with an H1 that repeats the title; drop it if your template prints the title itself.

{
  "article": {
    "id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76",
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "status": "finished",
    "title": "How to choose a product analytics tool for B2B SaaS",
    "slug": "how-to-choose-a-product-analytics-tool-for-b2b-saas-f2b8c1d4",
    "keyword": "product analytics tool for b2b saas",
    "description": "A buyer's checklist for B2B SaaS teams: the events to track, the questions to ask vendors and the traps to avoid.",
    "body": "# How to choose a product analytics tool for B2B SaaS\n\nChoosing a product analytics tool comes down to three things…\n\n**[Image: A checklist on a desk] (alt: \"Product analytics buying checklist\")**\n\n## What a B2B SaaS team needs to measure\n…see [retention analysis](#internal: retention guide)…",
    "body_markdown": "# How to choose a product analytics tool for B2B SaaS\n\nChoosing a product analytics tool comes down to three things…\n\n## What a B2B SaaS team needs to measure\n…see retention analysis…",
    "body_html": "<h1>How to choose a product analytics tool for B2B SaaS</h1>\n<p>Choosing a product analytics tool comes down to three things…</p>\n<h2>What a B2B SaaS team needs to measure</h2>\n<p>…see retention analysis…</p>",
    "tags": ["product analytics", "b2b saas"],
    "seo_score": 100,
    "traffic_estimate": 1400,
    "competition": "Medium",
    "ai_signal": 86,
    "scheduled_date": null,
    "queue_position": null,
    "notes": "",
    "published_url": null,
    "published_at": null,
    "dashboard_url": "https://rankbox.xyz/dashboard/editor/f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76",
    "created_at": "2026-10-02T14:05:40Z",
    "updated_at": "2026-10-02T15:25:31Z"
  }
}

Article statuses

finished means ready in Rankbox, not necessarily live on the website. published_url says where it is live. See How publishing works.

List articles

GET /sites/{site_id}/articles

Sorted by updated_at, newest first. Returns { "articles": [ … ], "next_cursor": … }.

Create an article

POST /sites/{site_id}/articles

Adds a topic to the plan, or an article you wrote yourself.

Returns 201 with { "article": { … } } and fires article.created.

Get an article

GET /sites/{site_id}/articles/{article_id}

Returns { "article": { … } } with all three bodies, as in The article object.

Update an article

PATCH /sites/{site_id}/articles/{article_id}

An article that is generating can't be changed (409 conflict). Changes to a finished article are saved and fire article.updated, but a connected Webflow or Shopify site keeps the previous version until you call Publish an article, like Publish changes in the editor. Site keys see the change at once.

Delete an article

DELETE /sites/{site_id}/articles/{article_id}

Deletes the article permanently and returns { "deleted": true, "id": "…" }. A credit spent writing it isn't returned. Copies already pushed to Webflow or Shopify, or pulled by a website, aren't removed from those places. An article that is generating can't be deleted until the job ends.

Generate an article

POST /sites/{site_id}/articles/{article_id}/generate

Writes the article, like Write now in the dashboard. It works on an opportunity or scheduled article and uses its title, keyword and description as the brief, plus the site's writing settings.

What happens:

1. Rankbox checks that the site may generate (an active trial with a card that passed the check, or the paid plan) and reserves 1 article credit.
2. The article moves to generating and a job starts. The call returns 202 with { "job": { … "type": "article.generate" … } }.
3. The writer researches the pages that rank for the keyword, drafts the article, scores it and rewrites what failed. If the site takes part in the backlink exchange, one link to another member's page may be placed in it.
4. On success the article becomes finished, its seo_score is stored, it is pushed to every connected Webflow or Shopify destination, and article.generated and article.finished fire. The job's result has article_id, status, seo_score, credits_spent and deliveries.
5. On failure the article returns to its previous status, the credit is refunded and article.generation_failed fires.

Errors: 402 subscription_required, 402 insufficient_credits, 409 conflict (already finished or generating), 429 rate_limited (the AI limit, or 3 generations already in progress on this site). To rewrite a finished article, edit it with PATCH and rewrite-section. See How articles are written.

Rewrite a section

POST /sites/{site_id}/articles/{article_id}/rewrite-section

Rewrites one passage, like the editor's AI actions on selected text. Synchronous, usually 5 to 15 seconds. No credits; counts toward the AI rate limit.

{
  "rewrite": {
    "action": "shorten",
    "result": "Pick the tool that answers your three core questions without SQL.",
    "applied": true
  },
  "article": { "id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76", "updated_at": "2026-10-02T15:40:10Z" }
}

article is the full article when applied is true, and null otherwise. With apply: true, a selection that doesn't appear in body returns 422 validation_failed.

Score an article

GET /sites/{site_id}/articles/{article_id}/score

Scores the current body exactly the way the editor does. Deterministic and free.

{
  "analysis": {
    "score": 92,
    "checks": [
      { "id": "kw-title", "label": "Keyword in title", "status": "pass", "detail": "\"product analytics tool for b2b saas\" appears in the title." },
      { "id": "faq", "label": "FAQ for AI engines", "status": "pass", "detail": "FAQ section helps AI answer engines cite you." },
      { "id": "meta", "label": "Meta description", "status": "warn", "detail": "172 characters — aim for 120–160." }
    ],
    "metrics": {
      "words": 2140,
      "reading_time": 10,
      "keyword_density": 0.9,
      "keyword_count": 19,
      "h2": 7,
      "h3": 9,
      "links": 6,
      "readability": 52,
      "readability_grade": "Standard"
    }
  }
}

Check IDs: kw-title, kw-intro, kw-density, words, h2, h3, lists, faq, meta, links, readability. Each status is pass, warn or fail. See The SEO and GEO score.

Finish an article

POST /sites/{site_id}/articles/{article_id}/finish

Marks an article you wrote yourself as finished, like Publish in the editor on a hand-written draft. The body must not be empty. No credit is spent. The article leaves the queue (scheduled_date and queue_position become null), is pushed to connected destinations, becomes visible to site keys and fires article.finished.

{
  "article": { "id": "0c2e4a6b-8d1f-4a3c-9e5b-7d9f1b3d5e82", "status": "finished" },
  "deliveries": [
    { "destination": "webflow", "result": "created", "reason": null, "url": "https://northwind.example/blog/onboarding-metrics", "draft": false, "error": null }
  ]
}

article holds the full article; it is shortened here. Errors: 409 conflict when already finished or generating, 422 validation_failed when body is empty. Generated articles are finished already and don't need this call.

Publish an article

POST /sites/{site_id}/articles/{article_id}/publish

For a finished article: pushes the current version to every connected push destination (like Publish changes) and, if you send it, records where the article is live.

POST /sites/6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64/articles/f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76/publish
Content-Type: application/json

{ "published_url": "https://northwind.example/blog/how-to-choose-a-product-analytics-tool-for-b2b-saas" }

{
  "article": {
    "id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76",
    "status": "finished",
    "published_url": "https://northwind.example/blog/how-to-choose-a-product-analytics-tool-for-b2b-saas",
    "published_at": "2026-10-02T16:02:44Z"
  },
  "deliveries": []
}

A delivery has destination (webflow or shopify), result (created, updated, unchanged, skipped or failed), reason for skipped deliveries (in_progress, edited_in_destination, deleted_in_destination, no_plan), url, draft and error. An article edited or deleted on the platform itself is never overwritten or re-created. Recording published_url fires article.published and is what the backlink exchange uses to verify links hosted in the article. Pushing needs a trial or plan; recording a URL doesn't. Errors: 409 conflict when the article isn't finished, 422 validation_failed when the URL isn't on the site's domain. See Live URLs and verification.

Jobs

The job object

Jobs are kept for 7 days. A failed article.generate job's error.code is generation_failed or timeout; its credit is always refunded.

Get a job

GET /jobs/{job_id}?wait=30

wait (0 to 30 seconds, default 0) holds the request open until the job finishes or the time runs out, whichever comes first. A loop of wait=30 calls is the cheapest way to wait for a job; each call counts as one request.

{
  "job": {
    "id": "9a7e5c3b-1d2f-4e6a-8b9c-0d1e2f3a4b5c",
    "type": "article.generate",
    "status": "completed",
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "resource": { "type": "article", "id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76" },
    "result": {
      "article_id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76",
      "status": "finished",
      "seo_score": 100,
      "credits_spent": 1,
      "deliveries": []
    },
    "error": null,
    "created_at": "2026-10-02T15:22:05Z",
    "started_at": "2026-10-02T15:22:06Z",
    "finished_at": "2026-10-02T15:25:31Z"
  }
}

List jobs

GET /jobs?status=queued,running&site_id=6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64

Filters: status, type, site_id, plus limit and cursor. Newest first. Use it after a restart to pick up jobs you lost track of.

Autopilot

The autopilot object

Autopilot writes the scheduled article with the lowest queue_position, then the earliest scheduled_date, spends 1 article credit, finishes it and pushes it to connected destinations. Articles it writes fire the same events as generate, with trigger: "autopilot". See Autopilot and the publishing schedule.

Get autopilot

GET /sites/{site_id}/autopilot

Returns { "autopilot": { … } }.

Update autopilot

PATCH /sites/{site_id}/autopilot
Content-Type: application/json

{ "enabled": true, "weekly_cadence": 3 }

Both fields are optional. Returns the updated object, as in step 12 of the quickstart.

Integrations

The integration object

pending means a connect link is waiting for the owner. setup means connected but not configured. idle is a pull integration whose keys haven't been used for 48 hours.

Settings by platform:

List integrations

GET /sites/{site_id}/integrations

{
  "integrations": [
    { "id": "webflow", "name": "Webflow", "delivery": "push", "available": true, "status": "not_connected", "connected_at": null, "last_published_at": null, "last_error": null, "settings": null, "counts": null },
    { "id": "rest_api", "name": "REST API", "delivery": "pull", "available": true, "status": "active", "connected_at": "2026-10-02T15:30:12Z", "last_published_at": "2026-10-02T15:58:03Z", "last_error": null, "settings": { "keys": 1, "last_key_used_at": "2026-10-02T15:58:03Z" }, "counts": null }
  ],
  "next_cursor": null
}

All five integrations are always listed; this example is shortened. The publishing pages say which platform add-ons are open to every account.

Get an integration

GET /sites/{site_id}/integrations/{integration_id}

Returns { "integration": { … }, "options": { … } }. options lists the choices for configuring a connected push integration:

• webflow: webflow_sites (id, display_name, domain, published). Add ?webflow_site_id= to also get collections (id, display_name, slug), and add &collection_id= to get fields (slug, display_name, type, is_required) and suggested_field_map.
• shopify: blogs (id, title).
• Pull integrations: options is null.

Connect an integration

POST /sites/{site_id}/integrations/{integration_id}/connect

Starts a connection. Needs a trial or plan. What comes back depends on the platform:

{
  "connection": {
    "integration_id": "webflow",
    "status": "pending",
    "authorize_url": "https://rankbox.xyz/connect/webflow/cr_xxxxxxxxxxxx",
    "install_url": null,
    "site_key": null,
    "expires_at": "2026-10-09T15:31:00Z"
  }
}

The connect page shows the owner which site and which agent asked. When they finish, integration.connected fires and status becomes setup (Webflow, Shopify) or active. Errors: 402 subscription_required, 409 integration_unavailable when available is false, 409 conflict when already connected.

Configure an integration

PATCH /sites/{site_id}/integrations/{integration_id}

Finishes setup of a push integration. Pull integrations have nothing to configure (409 conflict).

PATCH /sites/6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64/integrations/webflow
Content-Type: application/json

{
  "webflow_site_id": "64f1a2b3c4d5e6f708192a3b",
  "collection_id": "64f1a2b3c4d5e6f708192c4d",
  "field_map": { "body": "post-body", "summary": "post-summary", "tags": null, "published_at": "published-date" },
  "publish_mode": "draft"
}

Returns { "integration": { … "status": "active" … } }. A field map the collection won't accept returns 422 validation_failed with one details entry per problem. See Webflow and Shopify.

Sync an integration

POST /sites/{site_id}/integrations/{integration_id}/sync

Pushes every finished article that isn't on the platform yet and every article changed since its last push. Returns 202 with an integration.sync job. The result:

{ "created": 12, "updated": 1, "unchanged": 3, "skipped": 1, "failed": 0, "remaining": 0, "errors": [] }

When remaining is above 0, the run stopped at its time limit: call sync again. Pull integrations return 409 conflict; they sync from their own side.

Disconnect an integration

DELETE /sites/{site_id}/integrations/{integration_id}

Stops pushing to the platform. For Webflow, Rankbox deletes its stored token. For Shopify, the site is unlinked; the app stays installed until the merchant removes it. Items already on the platform stay there. Returns { "integration": { … "status": "disconnected" … } }. To stop a pull integration, revoke its site keys.

Site keys

Site keys (rv_live_…) let a website or plugin read one site's finished articles through the public API. Create them for the website; never deploy the agent key.

List site keys

GET /sites/{site_id}/keys

{
  "site_keys": [
    {
      "id": "7b9d1f3a-5c7e-4a2b-9d4f-6e8a0c2b4d61",
      "name": "northwind.example website",
      "prefix": "rv_live_d4e5f6…",
      "last_used_at": "2026-10-02T15:58:03Z",
      "revoked_at": null,
      "created_at": "2026-10-02T15:30:12Z"
    }
  ],
  "next_cursor": null
}

Revoked keys are included, with revoked_at set.

Create a site key

POST /sites/{site_id}/keys
Content-Type: application/json

{ "name": "northwind.example website" }

name is optional, at most 60 characters, default API key. Returns 201 with { "site_key": { … "key": "rv_live_xxxxxxxxxxxx" … } }; the secret is shown only here. Needs a trial or plan (402 subscription_required), and a site key stops working while the account has neither.

Revoke a site key

DELETE /sites/{site_id}/keys/{key_id}

Returns { "site_key": { … "revoked_at": "2026-10-03T09:00:00Z" } }. Revocation is immediate and permanent.

Credits

Get credits

GET /sites/{site_id}/credits

Each site has its own balances.

{
  "credits": {
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "articles": { "total": 7, "used": 1, "remaining": 6, "period_end": "2026-10-09T15:20:44Z" },
    "backlinks": { "balance": 0, "escrowed": 0, "period_end": null },
    "reddit_replies": { "balance": 0, "period_end": null }
  }
}

See Plans and credits.

Rank

Get Rank

GET /sites/{site_id}/rank

The Rank page's data: how much of the site's tracked keyword market has a finished article. It doesn't measure rankings or AI citations; searches and traffic are estimates.

{
  "rank": {
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "coverage": { "basis": "searches", "total": 48200, "published": 6100, "planned": 21900, "open": 20200 },
    "market": [
      {
        "keyword": "product analytics tool for b2b saas",
        "searches": 1900,
        "intent": "Commercial",
        "trend": "Rising",
        "traffic_estimate": 1400,
        "status": "published",
        "article_id": "f2b8c1d4-7e3a-4b9c-a6d5-3e8f1a2b4c76",
        "score": 100
      }
    ]
  }
}

coverage.basis is searches when keywords have search volumes (the totals are monthly searches) and topics otherwise (the totals are keyword counts). A market row's status is published, writing, scheduled, idea or gap. See Rank: AI search visibility.

Backlinks

The backlink exchange is paid-only: reads work on any account, changes need a paid plan (402 paid_plan_required). Credits settle only when a link is verified live. See Backlink exchange.

Get the backlink overview

GET /sites/{site_id}/backlinks

{
  "backlinks": {
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "paid": true,
    "domain": "northwind.example",
    "status": "verified",
    "verified_at": "2026-10-17T11:02:00Z",
    "opted_in": true,
    "authority_score": 34,
    "tier": 2,
    "reputation": 100,
    "niche": "B2B product analytics",
    "topic_tags": ["product analytics", "saas metrics"],
    "blocked_categories": ["gambling", "crypto"],
    "max_links_per_article": 1,
    "credits": { "balance": 30, "escrowed": 1, "lifetime_earned": 0, "lifetime_spent": 0 },
    "counts": { "live_inbound": 0, "live_hosted": 0, "in_progress": 1 }
  }
}

status is unverified, verifying, verified or suspended, or null before a domain is set.

Update backlink settings

PATCH /sites/{site_id}/backlinks

Returns the updated { "backlinks": { … } }.

Set the exchange domain

POST /sites/{site_id}/backlinks/domain
Content-Type: application/json

{ "domain": "northwind.example" }

Returns the ways to prove ownership. Any one of them works:

{
  "verification": {
    "domain": "northwind.example",
    "status": "unverified",
    "token": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "methods": {
      "dns_txt": { "host": "_rankbox.northwind.example", "value": "rankbox-site-verification=c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6" },
      "meta_tag": { "tag": "<meta name=\"rankbox-site-verification\" content=\"c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6\">" },
      "well_known": { "url": "https://northwind.example/.well-known/rankbox-verification", "content": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6" }
    }
  }
}

Verify the exchange domain

POST /sites/{site_id}/backlinks/domain/verify

Checks all three methods now. Counts toward the AI rate limit.

{
  "verification": {
    "domain": "northwind.example",
    "status": "verified",
    "checks": [
      { "method": "dns_txt", "ok": false, "seen": "no TXT record at _rankbox.northwind.example" },
      { "method": "well_known", "ok": false, "seen": "404" },
      { "method": "meta_tag", "ok": true, "seen": "meta tag matched" }
    ]
  }
}

List backlink targets

GET /sites/{site_id}/backlinks/targets

A target is a page on your site you want links to. Returns { "targets": [ … ], "next_cursor": null }. Each target has id, url, anchors, topic_tags, priority, max_new_links_per_month, active, live_count, last_placed_at and created_at.

Create a backlink target

POST /sites/{site_id}/backlinks/targets
Content-Type: application/json

{
  "url": "https://northwind.example/features/retention",
  "anchors": ["retention analysis", "cohort retention tool", "Northwind retention reports"],
  "topic_tags": ["retention", "saas metrics"],
  "priority": 7,
  "max_new_links_per_month": 4
}

Returns 201 with { "target": { … } }. At most 25 targets per site.

Update a backlink target

PATCH /sites/{site_id}/backlinks/targets/{target_id}

Any field of Create. Returns { "target": { … } }.

Delete a backlink target

DELETE /sites/{site_id}/backlinks/targets/{target_id}

Returns { "deleted": true, "id": "…" }. Links already live stay live.

List placements

GET /sites/{site_id}/backlinks/placements?direction=inbound&status=live

direction is inbound (links to your targets) or hosted (links your articles carry for others). status is any of reserved, placed, live, lost, expired, cancelled.

{
  "placements": [
    {
      "id": "6a8c0e2f-4b6d-4e8a-9c1e-3f5b7d9a1c34",
      "direction": "inbound",
      "status": "live",
      "target_url": "https://northwind.example/features/retention",
      "anchor_used": "cohort retention tool",
      "host_url": "https://partner.example/blog/saas-churn-playbook",
      "host_article_id": null,
      "credits": 2,
      "reserved_at": "2026-10-18T09:00:00Z",
      "placed_at": "2026-10-18T09:04:00Z",
      "live_at": "2026-10-19T06:00:00Z",
      "ended_at": null,
      "expires_at": "2026-11-17T09:00:00Z",
      "last_checked_at": "2026-10-25T06:00:00Z",
      "end_reason": null
    }
  ],
  "next_cursor": null
}

host_article_id is set on hosted placements: the article that carries the link.

Remove a hosted link

DELETE /sites/{site_id}/backlinks/placements/{placement_id}

For a hosted placement only. Rankbox unlinks the anchor in your article (the words stay). A live link's earned credits are clawed back; a link not yet live is cancelled and its credits return to the member who requested it. Returns { "placement": { … "status": "cancelled" … } }.

Reddit

Reddit Presence finds Reddit threads where the site's buyers ask questions and drafts replies. Rankbox never posts to Reddit and never holds a Reddit login: a person posts the reply from their own account and the agent records the permalink. Paid-only: reads work on any account, actions need a paid plan. See Reddit Presence.

Get Reddit Presence

GET /sites/{site_id}/reddit

{
  "reddit": {
    "site_id": "6f1c2a9e-4b7d-4e2a-8c3f-1d9e5b7a2c64",
    "access": "paid",
    "enabled": true,
    "sweep_enabled": true,
    "niche": "B2B product analytics",
    "topic_tags": ["product analytics", "saas metrics"],
    "disclosure_line": "Full disclosure: I work on {brand}.",
    "tone": "plain",
    "max_links_per_reply": 1,
    "allow_subreddits": [],
    "deny_subreddits": ["startups"],
    "keywords_per_sweep": 12,
    "last_sweep_at": "2026-10-18T06:00:00Z",
    "credits": { "balance": 28, "period_end": "2026-11-17T15:20:44Z" }
  }
}

access is paid, trial (shown the feature, can't use it yet), lapsed (history read-only) or none.

Update Reddit settings

PATCH /sites/{site_id}/reddit

Returns { "reddit": { … } }.

Start a Reddit sweep

POST /sites/{site_id}/reddit/sweeps

Searches Reddit now for threads matching the site's keywords. Free; counts toward the AI rate limit. Returns 202 with a reddit.sweep job whose result has threads_seen and opportunities_created. One sweep at a time per site (409 conflict).

List Reddit threads

GET /sites/{site_id}/reddit/threads?status=new,saved

status is any of new, saved, drafted, posted, dismissed, dead, stale. Best fit first.

{
  "threads": [
    {
      "id": "0e2c4a6b-8d1f-4c3e-9a5b-7d9f1b3d5e70",
      "status": "new",
      "fit": 82,
      "matched_keyword": "product analytics tool",
      "channel": "serp",
      "blocked_reason": null,
      "thread": {
        "reddit_id": "1f3k9qz",
        "subreddit": "saas",
        "permalink": "https://www.reddit.com/r/saas/comments/1f3k9qz/which_product_analytics_tool_for_a_10person_b2b/",
        "title": "Which product analytics tool for a 10-person B2B SaaS?",
        "up_votes": 48,
        "num_comments": 31,
        "posted_at": "2026-10-16T19:12:00Z",
        "is_locked": false
      },
      "draft": null,
      "reply": null,
      "first_seen_at": "2026-10-18T06:00:00Z"
    }
  ],
  "next_cursor": null
}

fit is 0 to 100, null for blocked threads; blocked_reason is archived, likely_archived, locked, removed, subreddit_denied, promo_banned or off_topic.

Get a Reddit thread

GET /sites/{site_id}/reddit/threads/{thread_id}

Returns { "thread": { … } } with the thread's body and top comments, the latest draft and the recorded reply.

Update a Reddit thread

PATCH /sites/{site_id}/reddit/threads/{thread_id}
Content-Type: application/json

{ "status": "dismissed", "dismiss_reason": "Asking for free tools only" }

status can be set to saved, dismissed or new (restore). A posted thread can't be dismissed.

Draft a Reddit reply

POST /sites/{site_id}/reddit/threads/{thread_id}/drafts
Content-Type: application/json

{ "instructions": "Mention the free plan only if asked." }

The first call drafts a reply and spends 1 Reddit reply credit. Later calls on the same thread rewrite the latest draft: 1 credit each, at most 3 rewrites, and the first rewrite is free when the draft failed a compliance check. instructions is optional, at most 500 characters. Synchronous.

{
  "draft": {
    "id": "8c0e2a4b-6d8f-4b1c-9e3a-5c7e9b1d3f46",
    "thread_id": "0e2c4a6b-8d1f-4c3e-9a5b-7d9f1b3d5e70",
    "body": "For a 10-person team, start from the three questions you need answered weekly…\n\nFull disclosure: I work on Northwind Analytics.",
    "edited_body": null,
    "compliance": {
      "pass": true,
      "failures": 0,
      "unknowns": 1,
      "checks": [
        { "id": "disclosure", "label": "Discloses that you work there", "state": "pass", "detail": "Says who you are up front." },
        { "id": "answers_first", "label": "Answers the question first", "state": "pass", "detail": "Helps before it mentions you." },
        { "id": "subreddit_rules", "label": "Subreddit rules", "state": "unknown", "detail": "Couldn't read this subreddit's rules. Check them before posting." }
      ]
    },
    "credits_spent": 1,
    "regen_count": 0,
    "created_at": "2026-10-18T09:20:00Z",
    "updated_at": "2026-10-18T09:20:00Z"
  }
}

Errors: 402 paid_plan_required, 402 insufficient_credits, 409 conflict after 3 rewrites or for a blocked thread. A refused or failed draft refunds its credit.

Edit a Reddit draft

PATCH /sites/{site_id}/reddit/drafts/{draft_id}
Content-Type: application/json

{ "edited_body": "For a 10-person team, start from the three questions…" }

Free. Returns { "draft": { … } }. The text to hand to a person is edited_body when set, otherwise body.

Record a posted reply

POST /sites/{site_id}/reddit/replies
Content-Type: application/json

{
  "thread_id": "0e2c4a6b-8d1f-4c3e-9a5b-7d9f1b3d5e70",
  "draft_id": "8c0e2a4b-6d8f-4b1c-9e3a-5c7e9b1d3f46",
  "permalink": "https://www.reddit.com/r/saas/comments/1f3k9qz/comment/lq2x8ab/"
}

Call this after a person has posted the reply from their own Reddit account. permalink must be a https://www.reddit.com/ link to a comment in that thread. Leave it out to record that a reply was posted before the link is known (status: "claimed"), then call again with it. One reply per thread per account.

{
  "reply": {
    "id": "2a4c6e8b-0d2f-4a4c-8e6b-9d1f3a5c7e58",
    "thread_id": "0e2c4a6b-8d1f-4c3e-9a5b-7d9f1b3d5e70",
    "draft_id": "8c0e2a4b-6d8f-4b1c-9e3a-5c7e9b1d3f46",
    "permalink": "https://www.reddit.com/r/saas/comments/1f3k9qz/comment/lq2x8ab/",
    "status": "posted",
    "score": null,
    "posted_at": "2026-10-18T10:05:00Z",
    "confirmed_at": null,
    "removed_at": null,
    "last_checked_at": null
  }
}

Rankbox then checks the comment on its own: status moves to confirmed (reddit.reply_verified), or removed or not_found (reddit.reply_removed). Recording and verifying never spend credits.

List Reddit replies

GET /sites/{site_id}/reddit/replies?status=posted,confirmed

Returns { "replies": [ … ], "next_cursor": … }.

Billing

The billing object

Get billing

GET /billing

Returns { "billing": { … } }, as in step 7 of the quickstart.

Create a checkout link

POST /billing/checkout

Creates a link for the owner to start the plan. The owner enters their card on Stripe's checkout page; Rankbox never sees the card number.

{
  "checkout": {
    "mode": "trial",
    "checkout_url": "https://rankbox.xyz/checkout/co_xxxxxxxxxxxx",
    "expires_at": "2026-10-09T14:07:02Z",
    "trial_days": 7,
    "price": { "amount": 49.5, "currency": "usd", "interval": "month" }
  }
}

mode is trial (7 days free, then $49.50 a month) for an account that has never had a subscription, and plan (charged today) for one whose earlier subscription ended. The link is valid for 7 days and can be opened more than once until checkout completes. When it does, billing.trial_started (or billing.activated) fires. An account with a current subscription gets 409 conflict; use the portal link instead.

Create a portal link

POST /billing/portal

Returns { "portal": { "portal_url": "https://rankbox.xyz/billing/portal/po_xxxxxxxxxxxx", "expires_at": "…" } }, valid for 24 hours. Stripe's billing portal is where the owner updates the card, downloads invoices and cancels. Hand it to the owner. Needs an existing subscription (409 conflict otherwise).

End the trial now

POST /billing/activate

Ends the trial today and charges the first $49.50 to the card on file, like Unlock everything now in Plan & Billing. The site's article balance resets to 30, and the backlink exchange, Reddit Presence and Studio open. Send an Idempotency-Key.

{
  "billing": { "status": "active", "paid": true, "current_period_end": "2026-11-04T10:00:00Z" },
  "charged": { "amount": 49.5, "currency": "usd" }
}

billing holds the full object; it is shortened here. Errors: 409 conflict when not trialing, 402 payment_failed with action_url when the card is declined (the trial continues), 403 human_required when the bank asks the cardholder to authenticate.

Get a Studio quote

GET /billing/studio-quote

What one more Studio site costs today, previewed by Stripe.

{
  "studio_quote": {
    "block": null,
    "message": null,
    "price_per_site": 49.5,
    "due_today": 24.75,
    "proration_date": 1760954400,
    "renews_at": "2026-11-04T10:00:00Z",
    "allowance": { "articles": 15, "backlink_credits": 15, "reddit_replies": 15 },
    "studio_sites": 0,
    "monthly_after": 99,
    "card": { "brand": "visa", "last4": "4242" }
  }
}

block says why a site can't be added now: no_plan, trialing, past_due, canceling or lapsed, with message in words. Pass proration_date to Add a Studio site within 30 minutes to be charged exactly due_today.

Events and webhooks

The payloads, signatures and retry rules are on Events and webhooks. These are the endpoints.

List events

GET /events?since=2026-10-02T14:00:00Z

Oldest first. Returns { "events": [ … ], "next_cursor": "…", "has_more": false }. next_cursor is always set, even when no events came back, so the next poll starts where this one ended. Events are kept for 30 days.

List webhooks

GET /webhooks

Returns { "webhooks": [ … ], "next_cursor": null }, without secrets.

Create a webhook

POST /webhooks

{
  "webhook": {
    "id": "5e3c1a9f-7b2d-4f8e-a1c3-6d4b2e9f8a17",
    "url": "https://agent.northwind.example/hooks/rankbox",
    "events": ["article.finished", "article.published", "credits.low"],
    "description": "Atlas",
    "enabled": true,
    "disabled_reason": null,
    "secret": "whsec_xxxxxxxxxxxx",
    "created_by": { "type": "agent", "id": "2d4f6a8c-1e3b-4c5d-8f7a-9b0c1d2e3f45", "name": "Atlas" },
    "created_at": "2026-10-02T16:10:00Z",
    "last_delivery_at": null,
    "last_delivery_status": null
  }
}

secret is shown only here. At most 10 endpoints per account.

Update a webhook

PATCH /webhooks/{webhook_id}

Change url, events, description or enabled. Setting enabled: true re-enables an endpoint Rankbox disabled after repeated failures. Returns { "webhook": { … } } without the secret.

Delete a webhook

DELETE /webhooks/{webhook_id}

Returns { "deleted": true, "id": "…" }. Deliveries in flight are dropped.

Send a test event

POST /webhooks/{webhook_id}/test

Sends a signed webhook.test event to the endpoint now and returns { "delivery": { "status": 200, "duration_ms": 184, "error": null } }.

Related

• Quickstart for AI agents: these endpoints in order.
• Events and webhooks: event types and signatures.
• Billing, credits and limits: plans, credits, rate limits.
• Agent MCP tools: the same operations as MCP tools.
• Errors: the public API's errors, which share this envelope.