Boost Boss API

The Boost Boss API lets you fetch ads, beacon events, and manage campaigns programmatically. This reference covers every endpoint, every parameter, and every response field. The API is organized around REST — predictable URLs, standard HTTP verbs, standard status codes, JSON request and response bodies.

If you're monetizing an AI app, start with the SDK quickstart. If you're running campaigns, skip to Create campaign. If you're integrating via OpenRTB, see our exchange docs.

Quickstart

Install the SDK, set your API key, fetch your first ad.

1. Install

npm install @boostboss/sdk
# or
pip install boostboss
# or
go get github.com/boostboss/go-sdk

2. Initialize the client

import { BoostBoss } from '@boostboss/sdk';

const bb = new BoostBoss({
  apiKey: process.env.BB_API_KEY,
  environment: 'live', // or 'test'
});

3. Fetch an ad

const ad = await bb.fetch({
  format: 'native',
  context: "help me refactor this python script",
  audience: 'ai-native',
});

// ad.headline  → "Ship better code 10× faster"
// ad.body      → "The AI coding assistant..."
// ad.cta_url   → "https://cursor.com/?ref=bb"
// ad.beacons   → { impression, click, convert }

Authentication

Boost Boss uses bearer tokens for authentication. Your API key must be passed in the Authorization header on every request.

Authorization: Bearer bb_sk_live_1a2b3c4d5e6f...

You have two key types:

• bb_sk_live_* — production secret key. Never ship to client code.
• bb_pk_live_* — production publishable key. Safe to expose in browser bundles.

Environments

Two environments. Both use the same SDKs and endpoints — you switch by using the corresponding keys.

TypeScript / JavaScript SDK

The recommended client for browsers, Node, and Deno. Zero dependencies, 8kb gzipped.

import { BoostBoss, NativeAd } from '@boostboss/sdk';

const bb = new BoostBoss({ apiKey: 'bb_sk_live_***' });

const ad: NativeAd = await bb.fetch({
  format: 'native',
  context: userMessage,
  mcpTools: ['filesystem', 'github'],
  model: 'claude-sonnet-4',
});

// Render the ad in your UI
renderCard({
  headline: ad.headline,
  body: ad.body,
  cta: ad.cta_text,
  onClick: () => ad.trackClick(),
});

Python SDK

from boostboss import BoostBoss

bb = BoostBoss(api_key="bb_sk_live_***")

ad = bb.fetch(
    format="native",
    context=user_message,
    mcp_tools=["filesystem", "github"],
    model="claude-sonnet-4",
)

if ad:
    render_card(ad.headline, ad.body, ad.cta_text)
    ad.track_click()  # on user click

Go SDK

import "github.com/boostboss/go-sdk"

bb := boostboss.New("bb_sk_live_***")

ad, err := bb.Fetch(ctx, &boostboss.FetchRequest{
    Format:   "native",
    Context:  userMessage,
    McpTools: []string{"filesystem", "github"},
    Model:    "claude-sonnet-4",
})
if err != nil { log.Fatal(err) }

Swift SDK

import BoostBoss

let bb = BoostBoss(apiKey: "bb_sk_live_***")

let ad = try await bb.fetch(
    format: .native,
    context: userMessage,
    mcpTools: ["filesystem", "github"]
)

Kotlin SDK

import ai.boostboss.BoostBoss

val bb = BoostBoss(apiKey = "bb_sk_live_***")

val ad = bb.fetch(
    format = "native",
    context = userMessage,
    mcpTools = listOf("filesystem", "github")
)

Fetch ad

Runs a real-time auction against your targeting parameters and returns the winning ad creative with signed beacon URLs. Median latency: 47ms p50, 180ms p99.

Request body

Example request

curl https://api.boostboss.ai/v1/ads/fetch \
  -H "Authorization: Bearer bb_sk_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "native",
    "context": "refactor this python function to use async",
    "audience": "ai-native",
    "mcp_tools": ["filesystem", "github"],
    "model": "claude-sonnet-4"
  }'

Example response

{
  "id": "ad_3Xc9wZ8fK4",
  "format": "native",
  "headline": "Ship better code 10× faster",
  "body": "The AI coding assistant that actually reads your codebase.",
  "cta_text": "Try Cursor free",
  "cta_url": "https://cursor.com/?ref=bb",
  "advertiser": { "name": "Cursor", "verified": true },
  "beacons": {
    "impression": "https://api.boostboss.ai/v1/beacon/imp/...",
    "click":      "https://api.boostboss.ai/v1/beacon/clk/...",
    "convert":    "https://api.boostboss.ai/v1/beacon/cvt/..."
  },
  "bid_cpm": 3.42,
  "match_score": 0.91,
  "latency_ms": 47
}

Impression beacon

The SDK fires this for you automatically on render. If you're hitting the API directly, fire this beacon the first time the ad is visible in the viewport (≥50% pixels, ≥1 second). Idempotent — duplicates are deduped server-side.

Click beacon

Fire before redirecting to the CTA URL. Returns 302 to the verified advertiser destination — so you can use it as the anchor's href directly.

Conversion beacon

Advertisers use this to report conversions back — signup complete, purchase made, install confirmed. Used by CPA bidders to pay per outcome.

List campaigns

Create campaign

Update campaign

Any field from Create campaign can be patched. Patching status to paused halts spend immediately. Patching creative triggers automatic creative re-review (typically under 15 minutes).

Get stats

Returns impressions, clicks, conversions, spend, and derived rates (CTR, CVR, eCPA) across the time range. Break down by campaign, format, host_app, intent_signal, or day.

{
  "range": { "from": "2026-04-01", "to": "2026-04-15" },
  "totals": {
    "impressions": 4_812_400,
    "clicks":      218_600,
    "conversions": 12_840,
    "spend_usd":   24810.00,
    "ctr":         0.0454,
    "cvr":         0.0587,
    "ecpa_usd":    1.93
  },
  "breakdown": [ ... ]
}

Ad formats

Boost Boss serves four native-first ad formats. Each is rendered by your app — we return the content, you render the chrome that matches your UI.

AI-native targeting

Boost Boss replaces cookie-based targeting with three session-level signals gathered from the MCP layer. All signals are anonymized and aggregated — no PII ever leaves the client.

Intent signals

Free-form intent extracted from the current user request. Examples: "debugging python", "writing pitch deck", "refactoring code". Advertisers bid on the intents that match what they sell.

Tool context

Which MCP tools are active in the session — filesystem, github, terminal, browser, slack, etc. Strong proxy for user activity type.

Model context

Which AI model is in use — claude-opus-4, gpt-5, gemini-3, etc. Useful for advertisers with model-specific integrations.

MCP integration

The SDK hooks into your MCP client automatically. On initialization, it registers a listener for tool calls and user messages, uses those signals as context and mcp_tools when fetching ads, and otherwise gets out of your way.

import { BoostBoss } from '@boostboss/sdk';
import { McpClient } from '@modelcontextprotocol/sdk';

const mcp = new McpClient({ /* ... */ });
const bb  = new BoostBoss({
  apiKey: 'bb_sk_live_***',
  mcpClient: mcp, // ← just pass it in
});

// The SDK now reads context from MCP automatically
const ad = await bb.fetch({ format: 'native' });

Webhooks

Receive real-time notifications for platform events. Configure endpoints in the dashboard → Settings → Webhooks.

Signature verification

Every webhook is signed with HMAC-SHA256. Verify with the signing secret from your dashboard:

import crypto from 'crypto';

const sig = req.headers['bb-signature'];
const expected = crypto.createHmac('sha256', SECRET)
  .update(req.rawBody).digest('hex');

if (crypto.timingSafeEqual(
  Buffer.from(sig),
  Buffer.from(expected)
)) {
  // ✓ verified — process event
}

Rate limits

We rate-limit per API key to protect both us and you. Limits are applied at the second and minute level with a rolling window.

Responses include three headers on every request:

X-RateLimit-Limit:      500
X-RateLimit-Remaining:  487
X-RateLimit-Reset:      1760521200

Error codes

Errors return a JSON body with a machine-readable code, a human message, and a request_id you can cite when contacting support.