API - Help Center

Creating an API key

Go to Settings → API and click Create key. Give it an optional name (e.g. “Production” or “CI/CD”) and click Create key.

The full key is shown only once, so copy it and store it somewhere safe. If you lose it, revoke the old key and create a new one.

You can create as many keys as you need. Each key is scoped to the organisation it was created in.

Authentication

Every request must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer bs_your_key_here

Endpoints

`GET /api/v1/mentions/:brand_id`

Returns a paginated list of processed mentions for a brand.

Query parameters

Parameter	Type	Description
`platform`	string	Filter by platform. One of `twitter`, `reddit`, `youtube`, `hackernews`, or `bluesky`.
`min_score`	0–100	Minimum relevance score. Defaults to `65`.
`limit`	1–100	Number of results per page. Defaults to `50`.
`offset`	number	Number of results to skip for pagination. Defaults to `0`.

Example request

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

Example response

{
  "data": [
    {
      "id": "01965a3b-...",
      "brandId": "01960c7e-...",
      "platform": "twitter",
      "sourceUrl": "https://x.com/user/status/...",
      "title": null,
      "content": "Just tried @acme and it's amazing...",
      "authorName": "Jane Doe",
      "authorUsername": "janedoe",
      "sentiment": "positive",
      "relevanceScore": 88,
      "publishedAt": "2026-03-15T14:30:00.000Z",
      "createdAt": "2026-03-15T15:01:12.000Z"
    }
  ],
  "total": 342,
  "limit": 10,
  "offset": 0,
  "hasMore": true
}

Response fields

Field	Type	Description
`id`	uuid	Unique mention ID.
`brandId`	uuid	The brand this mention belongs to.
`platform`	enum	One of `twitter`, `reddit`, `youtube`, `hackernews`, or `bluesky`.
`sourceUrl`	string \| null	Link to the original post.
`title`	string \| null	Title or headline (available for some platforms).
`content`	string \| null	Full text of the mention.
`authorName`	string \| null	Author's display name.
`authorUsername`	string \| null	Author's handle or username.
`sentiment`	string \| null	One of `positive`, `negative`, or `neutral`.
`relevanceScore`	number	AI-determined relevance score from 0 to 100.
`publishedAt`	ISO 8601	When the mention was originally published.
`createdAt`	ISO 8601	When BrandSonar imported the mention.

Pagination

The response includes total, limit, offset, and hasMore. To fetch the next page, increment offset by limit:

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

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an error message:

Status	Meaning
`400`	Invalid query parameter (e.g. unrecognised `platform` value).
`401`	Missing or invalid API key.
`404`	Brand not found (wrong `brand_id` or not in your organisation).