Developers

Build on PromptedBrand

Pull AI visibility, citations and opportunities into your own dashboards, BI tools and workflows. One REST API, JSON everywhere.

API referenceapi.promptedbrand.com/v1

Quickstart

From zero to your first visibility number in about five minutes.

1Create an API keyIn the app, open Settings › API keys and create a key (you need API access: admins have it, others get it from an admin in Settings › Team). Keys start with pb_live_. Agencies create keys in Agency settings; one key reads every client.Create API key
2Make your first requestSend the key as a Bearer token. Every response is JSON; lists are paginated with a cursor.
3Or try it without a keySigned in with API access? Every reference page has a Try it panel that runs real requests on your own data.

Request

curl https://api.promptedbrand.com/v1/brands \
  -H "Authorization: Bearer $PB_API_KEY"

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "brd_8f2kq1d9a0e44b6c9a1f0e2d3c4b5a69",
      "object": "brand",
      "name": "Northwind",
      "domain": "northwind.com",
      "engines": [
        "chatgpt",
        "perplexity",
        "gemini"
      ],
      "markets": [
        "US"
      ],
      "created": "2026-09-19T16:52:37Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Explore the API

Base URL https://api.promptedbrand.com/v1. All endpoints return JSON, use ISO 8601 dates and are versioned by date. Ids are prefixed by type: brd_, prm_, ans_, scn_.

Brands1 endpointThe brands this key can read: one for a workspace key, every client for an agency key.Visibility1 endpointHow visible a brand is in AI answers over a period: the score, the change against the previous period of the same length, share of voice, a time series and a breakdown per engine.Prompts1 endpointThe questions tracked for a brand, newest first..Answers1 endpointEvery AI answer collected for a brand, newest first, with the brands it mentions (in order) and the sources it cites..Citations1 endpointThe domains AI answers cite for a brand’s prompts over a period, most cited first, and how often they’re cited next to you..Competitors1 endpointThe competitors tracked for a brand, with their visibility over the last 30 days..Opportunities1 endpointRanked gaps where the brand could be named or cited: content gaps, sites to get listed on, technical blocks and wrong facts, with an estimated gain..Scans2 endpointsScan runs for a brand, newest first: the first scan, daily scans and manual ones..

Authentication

Send your secret key in the Authorization header on every request. Keep it on your server. Keys are read-only and can be revoked in Settings › API keys at any time.

Header

Authorization: Bearer pb_live_••••••••••••3f9a

A workspace key reads that brand. An agency key reads every active client; pass brand_id to choose one (list them with GET /v1/brands).

Errors

Errors use standard HTTP codes and a JSON body with a machine-readable code, a message and a request_id to quote if you contact us.

Status	Code	Meaning
400	invalid_request	A parameter is missing or malformed.
401	unauthorized	The API key is missing, revoked or wrong.
403	forbidden	Your role or the key doesn’t include this.
404	not_found	The resource doesn’t exist, or the key can’t see it.
429	rate_limited	Too many requests. Retry after the seconds in Retry-After.

Example

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "No valid API key provided.",
    "request_id": "req_9Qm2xA1b"
  }
}

Rate limits

60 requests a minute per key (and per person trying the API signed in), on every plan for now. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). A 429 includes Retry-After.

Pagination

Lists return { object: "list", data, has_more, next_cursor }. Pass limit (1 to 100) and, for the next page, cursor=next_cursor. Prompts, answers and scans use cursors; shorter lists come in one page.

Versioning

The API is v1, dated 2026-10-01 (sent back in the PromptedBrand-Version header). We only add fields and endpoints within a version; anything that would break your code gets a new version and notice in the changelog. The full spec is at /v1/openapi.json (OpenAPI 3.1).

Coming soon

Create and update prompts
Run scans
Webhooks
Content briefs
Reports
Official Node.js and Python SDKs

Webhooks will be signed with an HMAC SHA-256 PB-Signature header, for events like a finished scan, a competitor overtaking you and a new opportunity.

Changelog

v1 · 2026-10-01First public version: brands, visibility, prompts, answers, citations, competitors, opportunities and scans (read-only).