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 2.6, jump to the BBX adapter. Licensing Benna into your own mediation stack? Jump to Benna.

Quickstart

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

1. Install

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

2. Initialize the client

import { BoostBoss } from '@boostbossai/lumi-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.

SDKs

Official clients for every major language. Zero dependencies, tiny bundles, identical API surface. v1.0.0

npm install @boostbossai/lumi-sdk

import { BoostBoss, NativeAd } from '@boostbossai/lumi-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(),
});

pip install boostboss

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 get github.com/boostboss/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) }

.package(url: "https://github.com/boostboss/swift-sdk", from: "1.0.0")

import BoostBoss

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

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

implementation("ai.boostboss:sdk:1.0.0")

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"
  }'

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
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is missing, revoked, or for the wrong environment.",
    "request_id": "req_8f3a2c9d"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 1.2s.",
    "retry_after": 1.2,
    "request_id": "req_4b7e1f2a"
  }
}

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": [ ... ]
}

Benna — the ranking engine

Benna is the model that ranks every bid served through Boost Boss. It's an MCP-native ranker: instead of scoring on cookies, device IDs, and page URLs, it scores on the signals that actually predict conversion in an AI surface — user intent, the MCP tool about to be called, the host application, and session length. Benna runs at sub-5ms p50 and returns a full attribution block so every decision is inspectable.

Benna powers the first-party Boost Boss exchange (BBX) by default. You don't need to call it directly — the SDK does it for you. But if you operate your own demand stack and want to plug Benna into an existing mediation waterfall or header bidder, we license the raw inference endpoint at $0.002 per call. Every response includes the model version, predicted click & conversion rates, and a signal-by-signal contribution breakdown.

Score a bid request

Submit a bid context and a campaign spec; Benna returns an effective bid in USD plus click / convert probabilities and a signal attribution map. Billed at $0.002 per call; latency budget is 20ms end-to-end (model itself is 3–6ms, the rest is network & JSON).

Request

curl "https://boostboss.ai/api/benna" \
  -H "Authorization: Bearer bb_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "intent":      "debug_py",
      "mcp_tool":    "shell.exec",
      "host":        "cursor.com",
      "session_len": 42,
      "region":      "us-west"
    },
    "campaign": {
      "target_cpa": 8.00,
      "goal":       "target_cpa",
      "format":     "native"
    }
  }'

Response

{
  "model_version": "benna-rc3-2026.04.14",
  "bid_usd":          8.42,
  "p_click":          0.031,
  "p_convert":        0.0062,
  "signal_contributions": {
    "intent=debug_py":        0.34,
    "mcp_tool=shell.exec":    0.22,
    "host=cursor.com":        0.18,
    "session_len>30m":       0.13,
    "region=us-west":         0.09,
    "residual":               0.04
  },
  "latency_ms": 4.2
}

Engine status

Use this to confirm which model is live in production, when it was last retrained, and its self-reported calibration metrics. Free to call — not billed. Pair it with your own monitoring to alert on stale models or calibration drift.

{
  "model_version":      "benna-rc3-2026.04.14",
  "trained_through":    "2026-04-12",
  "training_examples": 184_000_000,
  "p50_latency_ms":     4.1,
  "p99_latency_ms":     11.8,
  "calibration_ece":    0.021,
  "status":             "healthy"
}

Signal reference

Benna is trained on five MCP-native signals. These are the only inputs that affect ranking — there are no cookies, no device fingerprints, no persistent user IDs. Intent strings are matched against a vocabulary server-side; raw text is discarded after normalization.

Weights shown are the current production contributions averaged across the live exchange; per-request attribution is returned in every /api/benna response so you can inspect the exact mix for any decision.

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 '@boostbossai/lumi-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.

OpenRTB 2.6 — BBX adapter

BBX (Boost Boss Exchange) exposes an OpenRTB 2.6 endpoint so that any compliant DSP — The Trade Desk, DV360, Amazon DSP, Criteo, or your in-house demand stack — can bid into MCP-native inventory without writing a bespoke integration. One URL, first-price auction, win/loss notices, native 1.2 + VAST 4.2 markup. The adapter sits in front of Benna: every bid is scored and every response includes a full attribution block in bid.ext.benna.

Endpoint summary

Bid request

Send a standard OpenRTB 2.6 BidRequest as the body. All supported objects — imp[], site / app, device, user, source, regs, bcat, badv — are honored. Native 1.2 asset requests pass through unchanged; the adapter parses imp.native.request and returns matching asset IDs in the response adm.

Minimum viable request: a BidRequest.id, a single imp with one of native / banner / video, and enough context to score. A realistic Trade Desk-style request looks like this:

curl -X POST https://boostboss.ai/api/rtb \
  -H 'Authorization: Bearer bb_seat_<your-seat-key>' \
  -H 'Content-Type: application/json' \
  -H 'x-openrtb-version: 2.6' \
  --data '{
    "id": "bid_req_9a8b7c",
    "at": 1,
    "tmax": 200,
    "cur": ["USD"],
    "imp": [{
      "id": "1",
      "tagid": "cursor.com/editor/python",
      "bidfloor": 1.50,
      "bidfloorcur": "USD",
      "secure": 1,
      "native": {
        "ver": "1.2",
        "request": "{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":60}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":628}},{\"id\":4,\"required\":1,\"data\":{\"type\":12,\"len\":25}}]}"
      }
    }],
    "site": {
      "id": "site_cursor_1",
      "domain": "cursor.com",
      "page": "https://cursor.com/editor",
      "keywords": "python debugging traceback editor",
      "publisher": { "id": "pub_cursor", "name": "Cursor Labs" }
    },
    "device": {
      "ua": "Mozilla/5.0 ...",
      "ip": "192.0.2.1",
      "geo": { "country": "USA", "region": "us-west" },
      "devicetype": 2
    },
    "user": { "id": "anon_sess_a1b2c3", "ext": { "session_len_min": 42 } },
    "source": { "tid": "tx_42f8", "fd": 1 },
    "bcat": ["IAB7-39", "IAB8-18"],
    "badv": ["bad-competitor.com"]
  }'

If your DSP already computes MCP signals server-side, pass them explicitly via imp.ext.mcp_context — they will override any values the adapter would otherwise infer. Example:

{ "imp": [{ "id": "1", "ext": { "mcp_context": {
  "intent": "debug_py",
  "mcp_tool": "filesystem.read",
  "host": "cursor.com",
  "region": "us-west",
  "session_len": 42
} } }] }

No-bid codes (NBR)

Bid response

On a win, the adapter returns a standard BidResponse with a single seatbid (seat = boostboss). Each bid carries CPM price (USD), creative markup, tracking URLs with the standard auction macros, and — critically — a bid.ext.benna attribution block that tells you exactly why the bid was scored the way it was.

{
  "id": "bid_req_9a8b7c",
  "bidid": "bbx_b1f42a6c3d9e",
  "cur": "USD",
  "seatbid": [{
    "seat": "boostboss",
    "bid": [{
      "id": "bbx_b1f42a6c3d9e",
      "impid": "1",
      "price": 148.20,
      "adid": "cam_datadog_001",
      "crid": "cr_datadog_apm_v3",
      "cid": "cam_datadog_001",
      "adomain": ["datadoghq.com"],
      "cat": ["IAB19-6"],
      "nurl": "https://boostboss.ai/api/rtb?op=win&imp=1&bid=bbx_b1f42a6c3d9e&price=${AUCTION_PRICE}",
      "lurl": "https://boostboss.ai/api/rtb?op=loss&imp=1&bid=bbx_b1f42a6c3d9e&reason=${AUCTION_LOSS}",
      "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[...],\"link\":{\"url\":\"https://...\"},\"eventtrackers\":[...]}}",
      "ext": {
        "benna": {
          "model_version": "benna-rc3-2026.04.14",
          "p_click": 0.0500,
          "p_convert": 0.0119,
          "latency_ms": 4,
          "signal_contributions": [
            { "signal": "intent=debug_py",    "weight": 0.34, "lift": 33.5 },
            { "signal": "host=cursor.com",    "weight": 0.18, "lift": 21.9 },
            { "signal": "region=us-west",     "weight": 0.09, "lift": 11.2 }
          ]
        }
      }
    }]
  }]
}

Key fields

Win / loss notices

Both notices are idempotent GETs that return a 43-byte 1×1 transparent GIF with Content-Type: image/gif. Fire them when your DSP resolves the auction. Substitute the standard OpenRTB macros before fetching:

# Win: substitute ${AUCTION_PRICE} with the clearing price in USD
GET /api/rtb?op=win&imp=1&bid=bbx_b1f42a6c3d9e&price=148.20

# Loss: substitute ${AUCTION_LOSS} with the OpenRTB loss reason code
GET /api/rtb?op=loss&imp=1&bid=bbx_b1f42a6c3d9e&reason=2

Common loss reasons (OpenRTB §5.24): 1 internal error, 2 impression opportunity expired, 3 invalid bid response, 102 below deal floor, 1001 lost to higher bid. BBX logs every notice and reconciles against Benna's internal price book.

Adapter status

A lightweight metadata endpoint for DSP discovery and health checks. Returns adapter version, supported formats, and Benna build info — useful for sandboxed QA and for your bidder's capability-negotiation phase.

{
  "adapter": "bbx-rtb-adapter",
  "adapter_version": "1.0.0",
  "openrtb_version": "2.6",
  "auction_type": 1,
  "supported_formats": ["native", "banner", "video"],
  "native_version": "1.2",
  "vast_version": "4.2",
  "benna_version": "benna-rc3-2026.04.14",
  "currencies": ["USD"]
}

OpenRTB → MCP signal map

BBX bridges OpenRTB's cookie/URL world and the MCP signal world that Benna actually scores on. The table below shows how the adapter infers MCP signals from standard OpenRTB fields. Any explicit imp.ext.mcp_context always wins — set it if your DSP has richer signal than the adapter can derive.

Response headers

Every BidResponse carries three BBX-specific headers for observability:

x-openrtb-version:     2.6
x-bbx-adapter:         bbx-rtb-adapter/1.0.0
x-bbx-processing-ms:   4

Changelog