# Rank Prompt Public API Documentation

The Rank Prompt Public API is a server-to-server REST API for managing brands, researching brand profiles, generating AI visibility reports, and orchestrating recurring runs. This page walks you from a fresh signup to your first end-to-end report in under 10 minutes.

## 1. Activate the Developer API

Open the [Developers page](https://app.rankprompt.com/developers) inside your Rank Prompt workspace and subscribe to an API plan. The plan controls how many **request units** and **credits** your account can consume each month. See [Pricing](/content/docs/v1/pricing/index.html) for the full breakdown.

## 2. Mint an API key

From the same Developers page, click **Create API key** and pick the scopes you need. The most common starter set is:

- `read:brands` + `write:brands`: manage brands and their researched facts.
- `read:reports` + `write:reports`: list, create, update and trigger reports. Reports include their prompts (and per-platform results) inline, so a single read covers everything you need to render a report.
- `write:prompts`: bulk-create, update and delete the prompts attached to a report. Reading prompts requires only `read:reports`.
- `read:region-configs` + `write:region-configs`: manage region configs and the prompts attached to each one.
- `read:scheduled` + `write:scheduled`: create and manage recurring schedules, trigger manual runs, and read run history / analytics.
- `read:webhooks` + `write:webhooks`: manage webhook endpoints so you get a signed callback on completion instead of polling. See [Webhooks](/content/docs/v1/webhooks/index.html).
- `read:jobs`: poll the status of asynchronous jobs.

Or pick `write:all` for full access while you’re prototyping. Keys begin with `rp_live_`; copy and store yours in a secret manager. **The full key is only shown once.**

## 3. Verify the key

Every request must carry an `Authorization: Bearer rp_live_...` header. The `/v1/me` endpoint is free (zero request units) and is the canonical "is my key valid?" check.

```
curl https://api.rankprompt.com/v1/me \
  -H "Authorization: Bearer rp_live_YOUR_KEY"
```

A `200` response means you’re in.

## 4. Create a brand

```
curl https://api.rankprompt.com/v1/brands \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-acme-prod" \
  -d '{"name": "Acme", "website": "https://acme.com"}'
```

The response carries the brand `id` (a UUID); you’ll pass it to every brand-scoped endpoint that follows.

## 5. Set the brand’s facts

The brand needs **facts** (a description plus optional industry, value proposition, key facts, …) before you can run an analysis or auto-generate prompts. Both pipelines feed `brand_info` into the LLM as required context. Endpoints that need facts return `422 brand_facts_required` until you set them. You have two ways to satisfy the requirement:

**Option A. Research them automatically** (recommended; 1 credit):

```
curl https://api.rankprompt.com/v1/brands/{brand_id}/facts \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Idempotency-Key: facts-acme-2026-04"
```

Returns `202 Accepted` with a `job_id` immediately; the research runs asynchronously. Poll `GET /v1/jobs/{job_id}` until `status` is `completed`, then `GET /v1/brands/{brand_id}/facts` to read the result.

**Option B. Set them manually** (free, no LLM):

```
curl https://api.rankprompt.com/v1/brands/{brand_id}/facts \
  -X PATCH \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "description": "Acme makes B2B CRM software for sales teams at SMBs.",\n    "industry": "SaaS",\n    "value_proposition": "All-in-one CRM at half the price of Salesforce."\n  }'
```

Only `description` is strictly required to unblock downstream endpoints; the other fields improve auto-generated prompt quality. You can always `PATCH` again later to refine them.

## 6. Create a report draft

`POST /v1/reports` always creates a **draft** report; no analysis is dispatched until you explicitly trigger it. Drafts let you review, edit, add or remove prompts before you spend credits running the analysis.

```
curl https://api.rankprompt.com/v1/reports \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-q4-acme-001" \
  -d '{\n    "brand_id": "{brand_id}",\n    "name": "Q4 visibility",\n    "country": "United States"\n  }'
```

The response carries the new draft `report_id` (a UUID).

## 7. Add prompts to the draft

You can either submit your own prompts or have the API auto-generate them. The endpoint is polymorphic: pass either `prompts` **or** `auto_generate`, not both.

```
# Manual: bulk insert prompts you wrote yourself
curl https://api.rankprompt.com/v1/reports/{report_id}/prompts \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "prompts": [\
      {"prompt_text": "best CRM for SaaS startups", "category": "CRM Software"},\
      {"prompt_text": "alternatives to Salesforce", "category": "CRM Software"}\
    ]\n  }'
```

```plaintext
# `category` names the **topic** the prompt is about (e.g. `CRM Software`, `Marketing Automation`). Two prompts about the same topic should share the same category so analytics can group them.
```

```
# Auto: synchronously generate prompts via LLM.
# Total prompts = prompts_per_category * len(categories); must be <= 50.
curl https://api.rankprompt.com/v1/reports/{report_id}/prompts \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "auto_generate": {\n      "prompts_per_category": 5,\n      "categories": ["CRM Software", "Marketing Automation", "Email Marketing"]\n    }\n  }'
```

You can also `PATCH` or `DELETE` individual prompts (`/v1/reports/{id}/prompts/{prompt_id}`) or wipe them all (`DELETE /v1/reports/{id}/prompts`) while the report is still in `draft` or `failed` state.

## 8. Trigger the analysis

Once the draft has at least one prompt, dispatch the analysis. This is the asynchronous step. You get back `202 Accepted` with a `job_id` to poll.

```
curl https://api.rankprompt.com/v1/reports/{report_id}/runs \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 9. Poll the job

```
curl https://api.rankprompt.com/v1/jobs/{job_id} \
  -H "Authorization: Bearer rp_live_YOUR_KEY"
```

Once `status` flips to `completed`, fetch the report. Its prompts and their per-platform results are returned inline, so a single GET covers everything you need to render the report:

```
curl https://api.rankprompt.com/v1/reports/{report_id} \
  -H "Authorization: Bearer rp_live_YOUR_KEY"
```

## 10. Schedule recurring runs (optional)

```
curl https://api.rankprompt.com/v1/scheduled-reports \
  -X POST \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "{brand_id}", "name": "Weekly", "frequency": "weekly"}'
```

`frequency` accepts `daily`, `weekly`, or `monthly`; `next_run_at` is computed from the frequency. Update it later with `PATCH /v1/scheduled-reports/{id}`.

A schedule needs at least one **region config** before it can run. Attach one via `POST /v1/region-configs` with `scheduled_report_id` set, then trigger a manual execution with `POST /v1/scheduled-reports/{id}/executions`.

The full brand → schedule → region config → prompt model is explained on the [Scheduled reports concept page](/content/docs/v1/schedules/index.html).