API quickstart

export BRANDVISIBILITY_API_URL="https://api.brandvisibility.ai"
export BRANDVISIBILITY_MCP_URL="https://mcp.brandvisibility.ai/mcp"

1. Create an organisation API key

Sign in to BrandVisibility and open Settings → API keys. Organisation owners and admins can create a key on a plan that includes API access. Select only the teams your integration needs and choose an expiry date.

Copy the key when it is displayed. It is shown once. Store it in your secret manager and inject it as BRANDVISIBILITY_API_KEY when running requests.

2. List your teams

curl --fail-with-body "https://api.brandvisibility.ai/api/v1/reporting/teams" \
  -H "Authorization: Bearer $BRANDVISIBILITY_API_KEY"

A response has this shape. All names and IDs below are synthetic:

{
  "data": [
    {
      "team_id": "11111111-1111-4111-8111-111111111111",
      "organization_id": "22222222-2222-4222-8222-222222222222",
      "name": "Example Agency Client"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false, "total": 1 }
}

3. Read one team’s reporting data

Set TEAM_ID to a team returned by the previous request:

export TEAM_ID="11111111-1111-4111-8111-111111111111"

curl --fail-with-body "https://api.brandvisibility.ai/api/v1/reporting/teams/$TEAM_ID/rankings" \
  -H "Authorization: Bearer $BRANDVISIBILITY_API_KEY"

Explore rankings, visibility, competitors, and citations. Follow pagination until next_cursor is null. A successful response can contain an empty data array when there is no reporting data for the chosen filters.

Python

import os
import requests

api_base = os.environ["BRANDVISIBILITY_API_URL"]
response = requests.get(
    f"{api_base}/api/v1/reporting/teams",
    headers={"Authorization": f"Bearer {os.environ['BRANDVISIBILITY_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
teams = response.json()["data"]

JavaScript on your server

const response = await fetch(`${process.env.BRANDVISIBILITY_API_URL}/api/v1/reporting/teams`, {
  headers: { Authorization: `Bearer ${process.env.BRANDVISIBILITY_API_KEY}` },
  signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`Reporting request failed: ${response.status}`);
const { data: teams } = await response.json();

Set BRANDVISIBILITY_API_URL to the API base URL in the environment panel above. Keep this code on your server so the key is not included in a client-side bundle.