Rankavi API Reference

Rankavi is a software as a service (SaaS) platform that publishes brand mentions in articles on indexed third-party websites. The Rankavi API lets you submit your own article for publication and list the available categories programmatically, without using the dashboard. API access is free; each published article uses one credit from your account.

Base URL

https://app.rankavi.com/api/v1

Authentication

Send your API key as a Bearer token in the Authorization header:

Authorization: Bearer rk_live_...

Create a key on the API Keys page of your dashboard. Keys are stored hashed, so a lost key cannot be shown again; create a new one instead. GET /categories needs no key.

Submit an article

POST /api/v1/mentions

Submits your own article for publication on an indexed website in the chosen category.

Request body

All three fields are required.

Field	Type	Description
`title`	string	The article title, up to 250 characters.
`body_html`	string	The full article as HTML, up to 5,000 words. It is published exactly as written. Name your brand in the text; mentions are unlinked.
`category`	string	One category name from `GET /categories`, case-insensitive, for example `Food and Drinks`.

{
  "title": "The 5 Best Coffee Roasters for Home Espresso in 2026",
  "body_html": "<p>Home espresso starts with fresh beans...</p>",
  "category": "Food and Drinks"
}

Example request

curl -X POST https://app.rankavi.com/api/v1/mentions \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The 5 Best Coffee Roasters for Home Espresso in 2026",
    "body_html": "<p>Home espresso starts with fresh beans...</p>",
    "category": "Food and Drinks"
  }'

Response (200)

{
  "success": true,
  "order": "RK-000005"
}

order is your Rankavi order number. One credit is used only when the order succeeds; if publishing fails, no credit is charged.

The response never includes the publication URL. Each live mention appears in My Mentions with its live link and Ahrefs metrics, and you get an email when it is live.

List categories

GET /api/v1/categories

Returns the 74 category names an article can be published under. No authentication required.

curl https://app.rankavi.com/api/v1/categories

Response (200)

{
  "categories": ["Adult", "Agriculture", "Animals", "Architecture", "Arts", "Auto"]
}

The response is shortened here; the full list has 74 names. Each category is a plain string. Send one of these names as category when you submit an article.

Errors

Every error returns a JSON body in this shape:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Code	Message
`401`	Invalid or missing API key
`400`	Missing required fields: title, body_html, category
`400`	Title is over the 250 character limit
`400`	Unknown category "X". See GET /api/v1/categories for the valid list.
`400`	Body is over the 5,000 word limit
`400`	Insufficient credits
`502`	Publishing failed and no credit was charged. Please try again or contact [email protected].
`500`	Internal error (also returned for a malformed JSON body)

Order status

The API has no endpoint for checking order status or listing mentions. Track each order in your dashboard, where it moves from pending to processing to published. A mention usually goes live within 24 hours.

Where to find your API key

Log in to your Rankavi dashboard and open the API Keys page to create a key. Full API docs are also available at app.rankavi.com/api-docs.