Boost Boss API reference

Boost Boss exposes a single REST surface at https://boostboss.ai covering two roles: publishers (hosting sponsored content in AI tools — every hosted impression mints 1 Credit) and advertisers (spending Credits, or cash, to promote their own product). The same account model unifies both — you sign up once, most devs are both sides at once. A machine-readable spec is at /openapi.json.

Jump to the role you came here for:

Authentication

Boost Boss uses JWT bearer tokens for the authenticated REST endpoints. There are no Stripe-style sk_live_* opaque keys — sign in with email + password, get back a signed JWT, and pass it on every subsequent request.

Login

curl https://boostboss.ai/api/auth?action=login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "..." }'

{
  "session": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in":   2592000,
    "token_type":   "Bearer"
  },
  "user": { "id": "...", "email": "you@example.com", "role": "advertiser" }
}

The token is a standard signed JWT — you can decode it client-side to read your user ID and role without making a network call. Pass it back on every subsequent request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

One special case

One surface doesn't use the user JWT. It uses a shared secret you configure once:

OpenRTB BBX seat key

DSPs hitting /api/rtb use a seat key issued at integration time, sent as a normal bearer header: Authorization: Bearer bb_seat_<key>. Contact support@boostboss.ai for seat onboarding.

Environments

One base URL: https://boostboss.ai. There is no separate api. subdomain.

Common patterns

Request and response shape

All endpoints accept and return JSON with Content-Type: application/json. The only exceptions are /api/track (also accepts a 1×1 GIF beacon GET) and /s/<token> (302 redirect).

Action multiplexing

Many endpoints multiplex multiple operations through one URL using an action query param — e.g. /api/campaigns?action=create, /api/auth?action=login. This is a deliberate choice to keep the Vercel function count low; treat each action value as a distinct logical endpoint.

Error envelope

Every error returns a JSON body with a machine-readable error field and (where applicable) a code field for programmatic branching. See Error codes.

{ "error": "Insufficient ad credit. Available: $34.30, requested: $50.00.",
  "code":  "insufficient_credit",
  "available": 34.30,
  "requested": 50.00 }

Idempotency

Where it matters — deposit capture, event tracking — endpoints are idempotent. Re-submitting the same operation returns the existing record with a deduped: true flag rather than producing duplicates.

PubPublisher endpoints

Publishers monetize AI surfaces — MCP servers, AI apps, browser extensions, Discord/Slack/Telegram bots. Pick the integration matching your deployment surface; all three call the same underlying auction.

• MCP servers → talk to /api/mcp directly via JSON-RPC, or install @boostbossai/lumi-mcp.
• Browser-side AI apps → drop in the /lumi.js script tag or install @boostbossai/lumi-sdk.
• Server-side bots → POST to /v1/ad-request with a publisher Bearer key.

Publishers earn Credits, not cash: every hosted impression mints 1 Credit, and Credits are spent to promote your own product across the network. There are no cash payouts. See Reporting for tracking what you've earned.

MCP JSON-RPC endpoint

The endpoint the @boostbossai/lumi-mcp SDK talks to. Implements three MCP methods: initialize (handshake), tools/list (enumerate the two tools), and tools/call (invoke get_sponsored_content or track_event). Auth: Authorization: Bearer <publisher_api_key>.

Request — tools/call · get_sponsored_content

{
  "jsonrpc": "2.0",
  "id":      1,
  "method":  "tools/call",
  "params": {
    "name":      "get_sponsored_content",
    "arguments": {
      "context":      "refactor this python function to use async",
      "active_tools": ["filesystem", "github"],
      "host_app":     "cursor",
      "surface":      "chat"
    }
  }
}

Response

A Benna-scored first-price auction result wrapped in the standard JSON-RPC envelope. result.content[0].text is a JSON-encoded payload with the ad fields plus signed tracking URLs. Beacons are pre-computed; track_event is provided as a convenience when the SDK can't fire URLs directly.

REST ad-request

Designed for server-side bot integrations (Discord, Telegram, Slack) where speaking JSON-RPC is overkill. Same underlying auction; flat input and output. Auth: Authorization: Bearer <publisher_api_key>.

Request body

Example

curl https://boostboss.ai/v1/ad-request \
  -H "Authorization: Bearer <publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "user wants to debug python traceback",
    "active_tools": ["filesystem", "shell"],
    "host_app": "cursor",
    "format": "card"
  }'

Track event (impression / click / close / skip / video_complete)

Fires on every ad lifecycle event. Feeds the billing ledger (advertiser spend) and publisher Credit accrual atomically per event — every hosted impression mints 1 Credit.

Request body

GET form (pixel beacon)

For environments where issuing a POST is awkward (HTML image tags, legacy email pixels), the same data can ride as query params on a GET — the response is a 1×1 transparent GIF.

GET /api/track?event=impression&campaign_id=cam_abc&format=card

AdvAdvertiser endpoints

Advertisers boost their products through the SuperBoost direct path via the /api/campaigns endpoints documented below. Auth: JWT bearer obtained from /api/auth?action=login as role advertiser.

List campaigns

Returns the array under campaigns. Filters: status (in_review / active / paused / rejected), limit, offset. Use ?id=<uuid> to fetch a single campaign.

Create campaign

First campaign per advertiser auto-approves if the creative passes policy. Subsequent campaigns enter in_review until an admin approves.

Required fields

Response (201)

{
  "campaign": { "id": "cam_...", "status": "in_review", ... },
  "policy":   { "ok": true, "violations": [] },
  "auto_approved": true
}

Update campaign

Pass id in the body. Any field from create can be updated. Editing creative re-runs policy. Setting status: "paused" halts spend immediately.

Get stats

Returns daily series + totals over the time range. Break down by campaign, format, host app, integration method, or day. The publisher-side counterpart is ?type=developer&key=<publisher_id>.

Deposit funds (add cash to amplify)

Cash flows one way: deposits amplify your promotion budget on top of the Credits you earn hosting. There is no cash-out — nothing ever flows back out of the platform.

Flow

1. Frontend POSTs create_checkout with the deposit amount. Backend creates a hosted checkout session and returns its URL.
2. Frontend redirects the advertiser to the checkout URL; the provider returns them to your configured return URL after approval.
3. The provider webhook reconciles asynchronously — the balance updates within seconds; poll action=balance after return.

Benna ranking engine

Benna is the model that ranks every bid served through Boost Boss — both the first-party SuperBoost direct path and the BBX OpenRTB exchange.

Benna powers BBX by default — you don't need to call it directly. The endpoints below exist for transparency (so any auction is inspectable) and for the longer-term plan to license the ranker into other mediation stacks.

Predict (score a bid context against a campaign)

Submit a context object + a campaign object; Benna returns an effective bid plus signal-by-signal contribution. Pricing is not currently billed.

Request

Response

{
  "model_version": "benna-stub-v1",
  "bid_usd":       8.42,
  "p_click":       0.031,
  "p_convert":     0.0062,
  "signal_contributions": [
    { "signal": "intent_overlap", "weight": 0.34 },
    { "signal": "tool_overlap",   "weight": 0.22 },
    { "signal": "host_match",     "weight": 0.18 }
  ],
  "latency_ms": 4.2
}

Engine status

Free to call. Returns the current model identity + aggregated diagnostics. Use this to alert on any future model swap.

OpenRTB 2.6 — BBX adapter

BBX (Boost Boss Exchange) exposes an OpenRTB 2.6 endpoint so any compliant DSP can bid into MCP-native inventory. First-price auction, native 1.2 + VAST 4.2 markup, Benna scoring on every bid with attribution in bid.ext.benna.

Endpoint summary

Bid request

Send a standard OpenRTB 2.6 BidRequest as the body. Supported objects: imp[], site / app, device, user, source, regs, bcat, badv. Native 1.2 asset requests pass through unchanged.

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

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": "..." }
    }],
    "site": { "id": "site_cursor_1", "domain": "cursor.com", "page": "https://cursor.com/editor", "keywords": "python debugging" },
    "device": { "geo": { "country": "USA", "region": "us-west" } },
    "user": { "id": "anon_sess_a1b2c3", "ext": { "session_len_min": 42 } }
  }'

If your DSP already computes MCP signals server-side, pass them via imp.ext.mcp_context — they override whatever the adapter would otherwise infer.

No-bid codes (NBR)

Bid response

Standard BidResponse with a single seatbid (seat = boostboss). Each bid carries CPM in USD, creative markup, tracking URLs with the standard auction macros, and a bid.ext.benna attribution block.

{
  "id": "bid_req_9a8b7c",
  "bidid": "bbx_b1f42a6c3d9e",
  "cur": "USD",
  "seatbid": [{
    "seat": "boostboss",
    "bid": [{
      "id": "bbx_b1f42a6c3d9e",
      "impid": "1",
      "price": 3.42,
      "adid": "cam_...",
      "adomain": ["datadoghq.com"],
      "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\":{...}}",
      "ext": {
        "benna": { "model_version": "benna-stub-v1", "p_click": 0.03, "signal_contributions": [...] }
      }
    }]
  }]
}

Win / loss notices

Both notices are idempotent GETs that return a 43-byte 1×1 transparent GIF. Substitute the standard OpenRTB macros before fetching:

# Win: substitute ${AUCTION_PRICE}
GET /api/rtb?op=win&imp=1&bid=bbx_b1f42a6c3d9e&price=3.42

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

Adapter status

Lightweight metadata endpoint for DSP discovery and health checks.

{
  "adapter": "bbx-rtb-adapter",
  "openrtb_version": "2.6",
  "auction_type": 1,
  "supported_formats": ["native", "banner", "video"],
  "benna_version": "benna-stub-v1",
  "currencies": ["USD"]
}

Webhooks

There is no unified webhook subscription system today. Money-in events are handled by two inbound webhooks:

Inbound: payment webhooks (deposits)

Cash flows one way on Boost Boss: in. Deposits credit your account balance; publishers earn Credits (never cash) by hosting ads. Two inbound handlers process deposit events server-side — there is nothing for you to integrate here:

• /api/paypal-webhook equivalent handling lives inside /api/billing — PAYMENT.CAPTURE.COMPLETED credits the advertiser balance (deposit); PAYMENT.CAPTURE.REFUNDED reverses the corresponding ledger row.
• /api/stripe-webhook — Stripe checkout deposits (checkout.session.completed, charge.refunded).

Rate limits

The platform applies coarse per-IP rate limits at the Vercel edge and per-account limits inside the handlers. The exact thresholds are tuned for normal operation rather than published as a hard contract — if you're approaching them legitimately, email support@boostboss.ai with the integration profile and we'll raise them. Beacon endpoints (/api/track) are effectively unlimited per impression; auction endpoints are protected to absorb bursts but not unlimited. We'll publish a fixed contract here once production load patterns are stable.

Error codes

Errors return a JSON body with at least an error field (human-readable). Many endpoints also include a code field for programmatic branching:

Changelog