REST API

One endpoint, read-only: your processed mentions as JSON. Enough to put them in a warehouse, a dashboard, or an internal tool.

Creating a key

Go to Settings → API and click Create key. Naming it is optional but worth doing, since “Warehouse sync” is easier to revoke confidently in a year than “Unnamed key”.

The API settings page listing one key named Production, showing only its prefix

The full key is shown once, at creation. Copy it then; afterwards only the prefix is visible. If you lose it, revoke that key and create another. There is no way to reveal it again.

Keys are scoped to the organisation they were created in and can read any brand in it, including competitors. Create as many as you need and revoke them individually.

Authentication

Pass the key as a bearer token. Every request needs it; there is no session or cookie alternative.

Authorization: Bearer bs_your_key_here

Keys are rate limited to 60 requests per minute.

Finding a brand ID

Every request is scoped to one brand. Brand IDs are UUIDs and appear in the app's URL when you open a competitor from Settings → Competitors. The brandId on any returned mention identifies which brand it belongs to.

List mentions

GET /api/v1/mentions/:brand_id

Returns processed, scored mentions for a brand, newest published first. Mentions still being analysed are not included.

Query parameters

platform: Restrict to one source: reddit, twitter, youtube, hackernews, or bluesky. Defaults to all.
min_score: Minimum relevance, 0–100. Defaults to 65, the same medium tier the app shows by default. Pass 0 for everything.
limit: Results per page, 1–100. Defaults to 50.
offset: Results to skip. Defaults to 0.

Example request

curl "https://brandsonar.com/api/v1/mentions/YOUR_BRAND_ID?limit=10&min_score=80" \
  -H "Authorization: Bearer bs_your_key_here"

Example response

{
  "data": [
    {
      "id": "019edc1a-6383-7c72-9f3c-e19dd5e91f6c",
      "brandId": "019edc1a-638b-7f00-8a15-ad4db80d44d7",
      "platform": "reddit",
      "sourceUrl": "https://reddit.com/r/emailmarketing/comments/...",
      "title": null,
      "content": "Trying to choose between Acme and the alternatives...",
      "authorName": "Priya R.",
      "authorUsername": "growth_priya",
      "sentiment": "positive",
      "relevanceScore": 94,
      "publishedAt": "2026-08-10T09:12:00.000Z",
      "createdAt": "2026-08-10T09:31:44.000Z"
    }
  ],
  "total": 342,
  "limit": 10,
  "offset": 0,
  "hasMore": true
}

Response fields

id: UUID for the mention.
brandId: UUID of the brand it belongs to, either your own or a competitor.
platform: Where it came from.
sourceUrl: Link to the original post. May be null.
title: Headline, where the platform has one. Null on platforms that do not.
content: The body text.
authorName: Display name, where available.
authorUsername: Handle, where available.
sentiment: positive, neutral, or negative.
relevanceScore: 0–100.
publishedAt: ISO 8601. When it was posted on the platform.
createdAt: ISO 8601. When BrandSonar imported it.

Labels are not included in the API response. Export from the mentions feed if you need them.

Pagination

Each response carries total, limit, offset, and hasMore. Walk the pages by advancing offset by limit until hasMore is false:

GET /api/v1/mentions/:brand_id?limit=50&offset=50

Errors

400: A query parameter is invalid: an unrecognised platform, or a limit out of range.
401: The API key is missing, malformed, or revoked.
403: The organisation has no paid plan, so API access is not enabled.
404: No brand with that ID in this key's organisation.

The API is available on paid plans. To be pushed data rather than poll for it, use a webhook alert.

Webhooks

The alert payload, its headers, and its signature.