> For the complete documentation index, see [llms.txt](https://rankavi.gitbook.io/rankavi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rankavi.gitbook.io/rankavi-docs/api-reference.md).

# API Reference

[Rankavi](https://rankavi.com/) is a software as a service (SaaS) platform that publishes brand mentions in articles on indexed third-party websites.

Submit brand mentions programmatically, from a script, an AI agent, or your own tooling. Each submission spends one credit and follows the same rules as the dashboard form.

Generate a key from [API Keys](https://app.rankavi.com/api-keys) to get started.

**Base URL:** `https://app.rankavi.com/api/v1`

## Authentication

Every request needs your key in the `Authorization` header, as a bearer token:

```
Authorization: Bearer rk_live_...
```

Keys are shown once when generated, then stored only as a hash on our side. A missing or unrecognized key returns `401`.

## POST /mentions

Submit a new mention. Places a real order and debits one credit on success.

### Request body

| Field       | Type   | Required | Notes                                                                                                                                                                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`     | string | Yes      | Up to 250 characters.                                                                                                                                                                                       |
| `body_html` | string | Yes      | Up to 5,000 words (HTML-stripped count). Allowed tags: `b`, `i`, `u`, `ul`, `li`, `p`, `strong`, `em`, `h1`-`h6`, `ol`, `table`, `caption`, `colgroup`, `col`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`. |
| `category`  | string | Yes      | Case-insensitive, must match a name from `GET /categories`.                                                                                                                                                 |

### Response

On success, `200`:

```json
{ "success": true, "order": "RK-000123" }
```

On any failure:

```json
{ "success": false, "error": "..." }
```

`order` is your Rankavi order number. The API never returns a publication URL, before or after a mention goes live. Each live mention appears in [My Mentions](https://app.rankavi.com/mentions) in your dashboard, and you get an email when it goes live.

## GET /categories

No authentication required. Lists all 74 valid category names.

When you submit a mention, the `category` field takes exactly one name from this list, as a single string. For example:

```json
{ "category": "Food and Drinks" }
```

## Errors

| Status | Meaning                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Missing/invalid field, unknown category, body over the word limit, or insufficient credits. See `error` for specifics.                     |
| `401`  | Missing or unrecognized API key.                                                                                                           |
| `502`  | Publishing failed, and no credit was charged. Rare, and not caused by anything in your request. Try again, or contact <hello@rankavi.com>. |
| `500`  | Unexpected server error. Safe to retry.                                                                                                    |

## Rate limits & credits

There's no separate request rate limit. Your credit balance is the real constraint, since every successful submission spends one credit. A request with zero balance returns `400` with `"Insufficient credits"` and never places an order.

Add credits any time from [Add Credits](https://app.rankavi.com/credits).

## Code examples

Ready-to-copy snippets in cURL, PHP, Python, and JavaScript are on the [API Keys](https://app.rankavi.com/api-keys) page, right below where you generate a key.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://rankavi.gitbook.io/rankavi-docs/api-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.