API docs v1

Quickstart

Make your first call to the Rank Prompt Public API in under 10 minutes.

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 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 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: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 '{
    "description": "Acme makes B2B CRM software for sales teams at SMBs.",
    "industry": "SaaS",
    "value_proposition": "All-in-one CRM at half the price of Salesforce."
  }'

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 '{
    "brand_id": "{brand_id}",
    "name": "Q4 visibility",
    "country": "United States"
  }'

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 '{
    "prompts": [
      {"prompt_text": "best CRM for SaaS startups", "category": "CRM Software"},
      {"prompt_text": "alternatives to Salesforce", "category": "CRM Software"}
    ]
  }'

# `category` names the **topic** the prompt is about (e.g. `CRM Software`,
# `Marketing Automation`). Two prompts about the same topic should share 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 '{
    "auto_generate": {
      "prompts_per_category": 5,
      "categories": ["CRM Software", "Marketing Automation", "Email Marketing"]
    }
  }'

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.

What’s next