BizReviewRadar logoBizReviewRadar
Start free

Developers · API reference

Biz Review Radar REST API

A versioned OpenAPI 3.1 surface for businesses, analyses, reports, recommendations, review reply drafts, and webhooks. This overview is public; the full interactive reference and spec download live in the signed-in developer portal.

Sign in for full docsAll developer docs

Base URL

Current
https://bizreviewradar.com/api/v1

Use this for every integration today. All examples on this page use it.

Planned
https://api.bizreviewradar.com

A dedicated API host is planned. It is not live yet: DNS and routing must be verified before docs, SDKs, or clients switch to it. Do not point production traffic at it.

When the dedicated host goes live, paths stay identical (/v1/…) and the current base URL keeps working.

Authentication

API keys

Available

Send Authorization: Bearer brr_test_…. Test-prefixed keys are issued for demo and private integrations. Live keys (brr_live_…) are issued by an administrator and only accepted while the live-keys flag is enabled for the account — assume test keys unless you have been told otherwise. Keys are shown once, stored only as a hash, and bound to your account's locked business.

OAuth 2.0 client-credentials

Available

For your own backend. Exchange a client ID and secret at POST /api/oauth/token for a short-lived JWT, then send it as a bearer token. See the OAuth guide.

OAuth 2.0 authorization-code + PKCE

Foundation · flag-gated

Implemented but disabled by default. Third-party public app registration is not open.

Main resources

Paths are relative to the base URL. Availability of individual resources depends on your plan's API entitlement.

Businesses

Your account's business record and its tracked competitors.

  • GET /businesses
  • GET /businesses/{id}
  • GET /businesses/{id}/competitors

Analyses

Competitor review analyses for a business.

  • GET /businesses/{id}/analyses
  • GET /analyses/{id}

Reports

Generated report documents tied to an analysis or purchase.

  • GET /reports/{id}

Recommendations

Prioritised, actionable recommendations for a business.

  • GET /businesses/{id}/recommendations

Review replies

AI-drafted review replies. Drafts only — you approve and post them.

  • POST /review-replies

Webhooks

Endpoints, delivery history, test events, and secret rotation.

  • GET /webhooks
  • POST /webhooks
  • GET /webhooks/{id}
  • GET /webhooks/{id}/deliveries
  • POST /webhooks/{id}/test
  • POST /webhooks/{id}/rotate-secret
  • POST /webhook-deliveries/{id}/resend

Events

Usage and account activity events for your API traffic.

  • GET /events

Example request and response

Dummy data for illustration.

curl https://bizreviewradar.com/api/v1/businesses/biz_123/analyses?limit=1 \
  -H "Authorization: Bearer brr_test_YOUR_KEY" \
  -H "Accept: application/json"
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_9f1c0d
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 41

{
  "data": [
    {
      "id": "an_456",
      "business_id": "biz_123",
      "status": "completed",
      "created_at": "2026-07-28T09:12:34Z",
      "competitors_analyzed": 9,
      "summary": {
        "positives": ["Fast service", "Friendly staff"],
        "negatives": ["Wait times on weekends"],
        "priorities": [
          { "priority": 1, "action": "Reply to 3 recent 1-star reviews" },
          { "priority": 2, "action": "Post 2 fresh photos this week" }
        ]
      }
    }
  ],
  "meta": {
    "request_id": "req_9f1c0d",
    "plan": "core",
    "rate_limit": { "limit": 60, "remaining": 59, "reset_s": 41 },
    "page": { "limit": 1, "next_cursor": "YW5fNDU2" }
  }
}

Every successful response wraps the payload in data and adds a meta object with the request ID, plan, rate-limit snapshot, and page info where applicable.

Error format

Errors use the same envelope with an error object instead of data. Branch on the stable machine-readable code, not on the human-readable message. Internal exception details are never returned.

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded."
  },
  "meta": { "request_id": "req_9f1c0d" }
}

unauthorized — missing, malformed, revoked, or expired credential (401).

forbidden — authenticated but not entitled to the resource (403).

not_found — unknown ID, or not owned by your account (404).

invalid_request — validation failure on body or query (400).

rate_limited — rate limit or quota exceeded (429).

internal_error — unexpected server error; retry with backoff (500).

Rate limits and fair use

Limits are applied per IP, per account, and per API key on a sliding window, and the configured numbers are adjustable by administrators. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 also carries Retry-After. Plan-level usage quotas apply on top of rate limits for metered actions such as running analyses.

Fair use: honour Retry-After, back off exponentially, cache responses where you can, and prefer webhooks over polling. Sustained abusive traffic can have its keys throttled or revoked.

Full OpenAPI 3.1 reference

The interactive reference, downloadable openapi.yaml, and per-endpoint cURL examples are available in the authenticated developer portal, alongside your keys, webhooks, and usage logs.

Open developer portalWebhook guide