Agency API

The Agency plan includes a REST API for reading site, widget, analytics, and loop data from AskBadge.

Authentication

Generate an API key from /dashboard/settings, then send it in the authorization header.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

Rate limit: 1000 requests per day per key. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

The same Agency API key also works with the AskBadge MCP server for Claude Desktop, Cursor, and other MCP clients.

Endpoints

Method	Path	Description
GET	/api/v1/sites	List all sites for the authenticated Agency account.
GET	/api/v1/sites/:siteId	Return one site with widget config and usage counts.
GET	/api/v1/sites/:siteId/analytics?days=30	Return click analytics, daily trend, and summary stats.
GET	/api/v1/sites/:siteId/analytics/loop?days=30	Return outbound-to-inbound AI traffic loop data.
GET	/api/v1/sites/:siteId/widget	Return the current widget configuration for that site.

Examples

cURL

curl https://askbadge.com/api/v1/sites \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx"

JavaScript

const res = await fetch("https://askbadge.com/api/v1/sites", {
  headers: {
    Authorization: "Bearer " + process.env.ASKBADGE_API_KEY,
  },
})

const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://askbadge.com/api/v1/sites",
    headers={"Authorization": f"Bearer {os.environ['ASKBADGE_API_KEY']}"},
)

print(res.json())

MCP server

AskBadge ships as a local MCP server so AI assistants can read site, analytics, loop, and widget data directly from your Agency account without browser copy-paste.

Available tools

Tool	Description
list_sites	List all sites in your AskBadge Agency account.
get_site	Get full details for a site, including widget config and counts.
get_analytics	Get click analytics for 7, 30, or 90 days.
get_loop_data	Get AI loop metrics showing outbound clicks and return visits.
get_widget_config	Get the current widget configuration for a site.

Claude Desktop

{
  "mcpServers": {
    "askbadge": {
      "command": "npx",
      "args": ["-y", "askbadge-mcp"],
      "env": {
        "ASKBADGE_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "askbadge": {
      "command": "npx",
      "args": ["-y", "askbadge-mcp"],
      "env": {
        "ASKBADGE_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Local development

cd mcp
pnpm install --ignore-workspace
pnpm build
ASKBADGE_API_KEY=sk_live_your_key_here node dist/index.js

The MCP server is read-only today. Account signup, checkout, verification changes, and site creation still happen in the dashboard or browser flows.