RankGuru API

The RankGuru API allows you to programmatically generate SEO-optimized content, analyze URLs, and publish articles to your CMS.

Base URL:

https://api.rankguru.pro/v1

Available on: Pro and Business plans

Authentication

Authenticate using Bearer tokens in the Authorization header.

Getting Your API Key

Go to Dashboard → Settings → API
Click Generate API Key
Copy and store securely (shown only once)

Making Requests

bash

curl https://api.rankguru.pro/v1/articles \
  -H "Authorization: Bearer rg_live_xxxxxxxxxx"

API Key Types

rg_live_* - Production keys
rg_test_* - Test keys (sandbox, no credits used)

Rate Limits

Plan	Requests/min	Requests/day
Pro	60	1,000
Business	120	5,000

Headers

Every response includes rate limit headers:

X-RateLimit-Limit: Max requests allowed
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

Exceeding Limits: Returns 429 Too Many Requests with Retry-After header.

Error Handling

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found
429	Rate Limited
500	Server Error

Error Response Format

json

{
  <span class="text-blue-400">"error"</span>: {
    <span class="text-blue-400">"code"</span>: <span class="text-green-400">"invalid_parameter"</span>,
    <span class="text-blue-400">"message"</span>: <span class="text-green-400">"The 'topic' parameter is required"</span>,
    <span class="text-blue-400">"param"</span>: <span class="text-green-400">"topic"</span>
  }
}

Pagination

List endpoints return paginated results with metadata about the current page and total items.

json

{
  <span class="text-blue-400">"data"</span>: [...],
  <span class="text-blue-400">"pagination"</span>: {
    <span class="text-blue-400">"page"</span>: <span class="text-orange-400">1</span>,
    <span class="text-blue-400">"limit"</span>: <span class="text-orange-400">10</span>,
    <span class="text-blue-400">"total"</span>: <span class="text-orange-400">45</span>,
    <span class="text-blue-400">"total_pages"</span>: <span class="text-orange-400">5</span>
  }
}

Generate Article

Create an AI-generated SEO-optimized article.

POST/v1/articles/generate

Request Body

Parameter	Type	Required	Description
topic	string	Required	Article topic or title
keywords	array	No	Target keywords
language	string	No	Language code (default: en)
word_count	number	No	Target words (500-5000, default: 1500)
tone	string	No	professional, casual, formal
template	string	No	Template ID to use
include_images	boolean	No	Generate AI images
include_videos	boolean	No	Suggest YouTube videos

Example Request

bash

curl -X POST https://api.rankguru.pro/v1/articles/generate \
  -H "Authorization: Bearer rg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Best SEO Tools in 2026",
    "keywords": ["seo tools", "seo software"],
    "language": "en",
    "word_count": 2000,
    "tone": "professional",
    "include_images": true
  }'

Response

json

 1{
 2  <span class="text-blue-400">"id"</span>: <span class="text-green-400">"art_abc123"</span>,
 3  <span class="text-blue-400">"status"</span>: <span class="text-green-400">"completed"</span>,
 4  <span class="text-blue-400">"title"</span>: <span class="text-green-400">"10 Best SEO Tools in 2026: Complete Guide"</span>,
 5  <span class="text-blue-400">"content"</span>: <span class="text-green-400">"<h1>10 Best SEO Tools...</h1>..."</span>,
 6  <span class="text-blue-400">"word_count"</span>: <span class="text-orange-400">2156</span>,
 7  <span class="text-blue-400">"seo_score"</span>: <span class="text-orange-400">92</span>,
 8  <span class="text-blue-400">"keywords_used"</span>: ["seo tools", "seo software"],
 9  <span class="text-blue-400">"images"</span>: [
10    {<span class="text-blue-400">"url"</span>: <span class="text-green-400">"https://..."</span>, <span class="text-blue-400">"alt"</span>: <span class="text-green-400">"SEO tools comparison"</span>}
11  ],
12  <span class="text-blue-400">"meta"</span>: {
13    <span class="text-blue-400">"title"</span>: <span class="text-green-400">"10 Best SEO Tools in 2026 | Expert Guide"</span>,
14    <span class="text-blue-400">"description"</span>: <span class="text-green-400">"Discover the top SEO tools..."</span>
15  },
16  <span class="text-blue-400">"created_at"</span>: <span class="text-green-400">"2026-01-09T12:00:00Z"</span>
17}

Credits Used: Standard article = 1 credit | With AI images = +0.5 credits per image

Try it out

POST/v1/articles/generate

Try it out

Parameters

topicrequired(string)

keywords(array)

word_count(number)

List Articles

Retrieve all articles for your account.

GET/v1/articles

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (max: 100)
status	string	Filter: draft, published, all
sort	string	created_at, updated_at, seo_score
order	string	asc or desc

Example Request

bash

curl https://api.rankguru.pro/v1/articles?limit=10&status=published \
  -H "Authorization: Bearer rg_live_xxx"

Response

json

 1{
 2  <span class="text-blue-400">"data"</span>: [
 3    {
 4      <span class="text-blue-400">"id"</span>: <span class="text-green-400">"art_abc123"</span>,
 5      <span class="text-blue-400">"title"</span>: <span class="text-green-400">"Best SEO Tools 2026"</span>,
 6      <span class="text-blue-400">"status"</span>: <span class="text-green-400">"published"</span>,
 7      <span class="text-blue-400">"seo_score"</span>: <span class="text-orange-400">92</span>,
 8      <span class="text-blue-400">"word_count"</span>: <span class="text-orange-400">2156</span>,
 9      <span class="text-blue-400">"created_at"</span>: <span class="text-green-400">"2026-01-09T12:00:00Z"</span>
10    }
11  ],
12  <span class="text-blue-400">"pagination"</span>: {
13    <span class="text-blue-400">"page"</span>: <span class="text-orange-400">1</span>,
14    <span class="text-blue-400">"limit"</span>: <span class="text-orange-400">10</span>,
15    <span class="text-blue-400">"total"</span>: <span class="text-orange-400">45</span>,
16    <span class="text-blue-400">"total_pages"</span>: <span class="text-orange-400">5</span>
17  }
18}

Get Article

Retrieve a single article by ID.

GET/v1/articles/:id

Path Parameters

id - Article ID (e.g., art_abc123)

Query Parameters

format - html (default), markdown, json

Example Request

bash

curl https://api.rankguru.pro/v1/articles/art_abc123 \
  -H "Authorization: Bearer rg_live_xxx"

Update Article

Update an existing article.

PATCH/v1/articles/:id

Request Body

Parameter	Type	Description
title	string	New title
content	string	New content (HTML)
status	string	draft or published

Example Request

bash

curl -X PATCH https://api.rankguru.pro/v1/articles/art_abc123 \
  -H "Authorization: Bearer rg_live_xxx" \
  -d '{"status": "published"}'

Delete Article

Permanently delete an article.

DELETE/v1/articles/:id

Example Request

bash

curl -X DELETE https://api.rankguru.pro/v1/articles/art_abc123 \
  -H "Authorization: Bearer rg_live_xxx"

Response

json

{
  <span class="text-blue-400">"deleted"</span>: <span class="text-purple-400">true</span>,
  <span class="text-blue-400">"id"</span>: <span class="text-green-400">"art_abc123"</span>
}

Export Article

Export article in various formats.

GET/v1/articles/:id/export

Query Parameters

format - pdf, docx, markdown, txt

Example Request

bash

curl https://api.rankguru.pro/v1/articles/art_abc123/export?format=pdf \
  -H "Authorization: Bearer rg_live_xxx"

Analyze URL

Get SEO analysis for any URL.

POST/v1/seo/analyze

Request Body

Parameter	Type	Required	Description
url	string	Required	URL to analyze
keyword	string	No	Target keyword to check

Response

json

 1{
 2  <span class="text-blue-400">"url"</span>: <span class="text-green-400">"https://example.com/blog/post"</span>,
 3  <span class="text-blue-400">"seo_score"</span>: <span class="text-orange-400">78</span>,
 4  <span class="text-blue-400">"issues"</span>: [
 5    {<span class="text-blue-400">"type"</span>: <span class="text-green-400">"warning"</span>, <span class="text-blue-400">"message"</span>: <span class="text-green-400">"Meta description too short"</span>},
 6    {<span class="text-blue-400">"type"</span>: <span class="text-green-400">"error"</span>, <span class="text-blue-400">"message"</span>: <span class="text-green-400">"Missing H1 tag"</span>}
 7  ],
 8  <span class="text-blue-400">"recommendations"</span>: [
 9    "Add keyword to title",
10    "Increase content length"
11  ],
12  <span class="text-blue-400">"metrics"</span>: {
13    <span class="text-blue-400">"word_count"</span>: <span class="text-orange-400">850</span>,
14    <span class="text-blue-400">"headings"</span>: {<span class="text-blue-400">"h1"</span>: <span class="text-orange-400">0</span>, <span class="text-blue-400">"h2"</span>: <span class="text-orange-400">3</span>, <span class="text-blue-400">"h3"</span>: <span class="text-orange-400">5</span>},
15    <span class="text-blue-400">"images"</span>: <span class="text-orange-400">2</span>,
16    <span class="text-blue-400">"links"</span>: {<span class="text-blue-400">"internal"</span>: <span class="text-orange-400">5</span>, <span class="text-blue-400">"external"</span>: <span class="text-orange-400">3</span>}
17  }
18}

Keyword Research

Discover related keywords for your topic.

POST/v1/seo/keywords

Request Body

Parameter	Type	Required	Description
keyword	string	Required	Seed keyword
country	string	No	Country code (default: US)
limit	number	No	Max results (default: 50)

Example Request

bash

curl -X POST https://api.rankguru.pro/v1/seo/keywords \
  -H "Authorization: Bearer rg_live_xxx" \
  -d '{"keyword": "seo tools", "country": "US", "limit": 20}'

Response

json

 1{
 2  <span class="text-blue-400">"keywords"</span>: [
 3    {
 4      <span class="text-blue-400">"keyword"</span>: <span class="text-green-400">"best seo tools"</span>,
 5      <span class="text-blue-400">"search_volume"</span>: <span class="text-orange-400">12000</span>,
 6      <span class="text-blue-400">"difficulty"</span>: <span class="text-orange-400">65</span>,
 7      <span class="text-blue-400">"cpc"</span>: <span class="text-orange-400">4</span>.25
 8    },
 9    {
10      <span class="text-blue-400">"keyword"</span>: <span class="text-green-400">"free seo tools"</span>,
11      <span class="text-blue-400">"search_volume"</span>: <span class="text-orange-400">8500</span>,
12      <span class="text-blue-400">"difficulty"</span>: <span class="text-orange-400">45</span>,
13      <span class="text-blue-400">"cpc"</span>: <span class="text-orange-400">2</span>.50
14    }
15  ]
16}

SERP Check

Check search engine rankings for a URL.

POST/v1/seo/serp

Request Body

Parameter	Type	Required	Description
url	string	Required	URL to check
keyword	string	Required	Keyword to check ranking for
country	string	No	Country code (default: US)

AI Detection Check

Check if content appears AI-generated.

POST/v1/seo/ai-detection

Request Body

Parameter	Type	Required	Description
content	string	Required	Text content to analyze

Response

json

{
  <span class="text-blue-400">"ai_score"</span>: <span class="text-orange-400">15</span>,
  <span class="text-blue-400">"classification"</span>: <span class="text-green-400">"human"</span>,
  <span class="text-blue-400">"confidence"</span>: <span class="text-orange-400">0</span>.92
}

WordPress Publish

Publish article directly to WordPress.

POST/v1/integrations/wordpress/publish

Request Body

Parameter	Type	Required	Description
article_id	string	Required	RankGuru article ID
site_id	string	Required	Connected WordPress site ID
status	string	No	publish or draft (default: publish)
categories	array	No	WordPress category IDs

Webflow Publish

Publish article directly to Webflow CMS.

POST/v1/integrations/webflow/publish

Request Body

Parameter	Type	Required	Description
article_id	string	Required	RankGuru article ID
site_id	string	Required	Connected Webflow site ID
collection_id	string	Required	Webflow collection ID

Webhook Events

Configure webhooks to receive real-time notifications about events in your RankGuru account.

Available Events

Event	Description
article.created	New article generated
article.published	Article published to CMS
credits.low	Credits below threshold

Webhook Payload

json

{
  <span class="text-blue-400">"event"</span>: <span class="text-green-400">"article.created"</span>,
  <span class="text-blue-400">"timestamp"</span>: <span class="text-green-400">"2026-01-09T12:00:00Z"</span>,
  <span class="text-blue-400">"data"</span>: {
    <span class="text-blue-400">"id"</span>: <span class="text-green-400">"art_abc123"</span>,
    <span class="text-blue-400">"title"</span>: <span class="text-green-400">"Best SEO Tools 2026"</span>,
    <span class="text-blue-400">"status"</span>: <span class="text-green-400">"completed"</span>
  }
}

Article Object

The article object represents a generated article.

Attributes

Attribute	Type	Description
id	string	Unique article identifier
title	string	Article title
content	string	HTML content
status	string	draft or published
seo_score	number	SEO score (0-100)
word_count	number	Total word count
created_at	string	ISO 8601 timestamp

Keyword Object

The keyword object contains SEO metrics for a keyword.

Attributes

Attribute	Type	Description
keyword	string	The keyword phrase
search_volume	number	Monthly search volume
difficulty	number	SEO difficulty (0-100)
cpc	number	Cost per click (USD)

Analysis Object

The analysis object contains SEO analysis results for a URL.

Attributes

Attribute	Type	Description
url	string	Analyzed URL
seo_score	number	Overall SEO score (0-100)
issues	array	List of issues found
recommendations	array	Improvement suggestions
metrics	object	Detailed metrics