Every answer and every receipt, over an API.

Authentication

Send a key as a bearer token. Create account keys under API keys in your account. A key is shown once, stored only as a hash, reads only, and can be revoked at any time. Your account shows when each key was last used.

Every account, free accounts included, can read its own data and the sample. Address your own account as me or by its id, and the sample as sample. Any other account id answers 404, exactly as an account that does not exist.

curl -H "Authorization: Bearer $BROADCASTWELL_KEY" \
  https://app.broadcastwell.com/api/v1/accounts/me/runs

Limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A caller over its allowance receives 429 with Retry-After in seconds. Lists return at most 100 items a page.

Conventions

Rates

Every rate is one object with five fields: pct, low, high, interval and base. low and high are the 95% Wilson interval. base states the count, for example 125 of 518 answers. Counts also appear as whole numbers beside every rate.

Scheduled and adaptive runs

Every headline figure counts scheduled runs only. Adaptive runs re-ask the question and engine pairs whose scheduled verdicts disagreed. They are returned separately, labelled, and never pooled. Re-measurement is monthly. A figure is said to have moved only when its interval and the earlier one do not overlap, and runs on different method versions are never compared.

Paging

Lists take limit (1 to 100, default 25) and return pagination.next_cursor. Pass it back as cursor until it is null.

Caching

Every response carries a strong ETag. Send it back as If-None-Match and an unchanged resource answers 304 with no body. A delivered measurement does not change and is cached for an hour.

Errors

Errors are problem details (application/problem+json) with a code and a detail that says what to do next.

{
  "type": "https://app.broadcastwell.com/developers#error-not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No run with that id is available to this key. List the parent collection to see the ids this key can read."
}

Versioning

Version 1 changes only by addition. Fields and routes are added; none is renamed or removed while version 1 is served. The full description is at /api/v1/openapi.json (OpenAPI 3.1).

Endpoints

Rendered from the OpenAPI description. Base address https://app.broadcastwell.com/api/v1.

curl "https://app.broadcastwell.com/vendors/kalvenor/facts.json"

curl "https://app.broadcastwell.com/standard/vendor-facts.schema.json"

curl "https://app.broadcastwell.com/api/v1/exclusive/check?category=dealership%20management%20systems"

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/checklist

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/briefs

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/briefs/{brief}

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/record

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/record/{record}

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/kpi

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/proof

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/me

curl "https://app.broadcastwell.com/api/v1/method"

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/summary

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/questions

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/questions/7

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/receipts

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/receipts/RECEIPT_ID

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/displacement

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/sources

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/fixes

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/runs/baseline-kalvenor-v11/compare/kalvenor-monitor

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/fixes

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/history

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/alerts

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/proof

curl -H "Authorization: Bearer bwp_demo_kalvenor_sample" \
  https://app.broadcastwell.com/api/v1/accounts/sample/proof/EXPERIMENT_ID

curl "https://app.broadcastwell.com/api/v1/index/lookup?domain=procore.com"

curl "https://app.broadcastwell.com/api/v1/index/categories"

curl "https://app.broadcastwell.com/api/v1/index/categories/crm"

curl "https://app.broadcastwell.com/api/v1/public-fix"

curl "https://app.broadcastwell.com/api/v1/public-fix/vantaa-tax"

Webhooks

Add a destination under Webhooks in your account. Destinations must use HTTPS on the standard port and a public address. Redirects are never followed. A Send test event button delivers a signed webhook.test event, and the account keeps a log of the last 50 delivery attempts.

Delivery and retries

Any 2xx response acknowledges an event. Anything else is attempted again, no sooner than 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours after the attempt before, and then abandoned.

Delivery is at least once. A slow answer or a lost acknowledgement can bring the same event to your address again. Every event carries a durable id, the same on every attempt and in the Broadcastwell-Event-Id header, so make your receiver idempotent on it: keep the ids you have processed and acknowledge a repeat without acting on it twice. Verify the signature on every delivery before you trust its body.

Verifying a signature

Each delivery carries Broadcastwell-Signature: t=<unix seconds>,v1=<hex>. The signature is HMAC SHA-256, keyed with your signing secret, over the timestamp, a full stop and the raw request body. Reject any timestamp more than 300 seconds from your clock: that window is your replay protection. Compare in constant time.

Node

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBroadcastwell(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(String(header).split(",").map((item) => item.split("=")));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const given = Buffer.from(String(parts.v1 || ""), "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Python

import hashlib
import hmac
import time


def verify_broadcastwell(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(",") if "=" in item)
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance_seconds:
        return False
    signed = str(timestamp).encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Slack and Teams

Paste a Slack incoming webhook address, or a Teams workflow or incoming webhook address, and choose its events. Chat destinations receive a short message with the receipts link, through the same delivery and retry path. Chat messages are not signed, so keep those addresses private.

Connector for AI assistants

The Broadcastwell connector is a read only MCP server. The public connector needs no token and no account: it reads the Absence Index, the Public Fix record, the method and the fictional sample, with the tools list_categories, get_index_category, find_vendor, get_public_fix, get_method, get_sample_run and run_free_check.

https://app.broadcastwell.com/mcp/public

The public sample connector needs no token either and reads every receipt of the fictional sample:

https://app.broadcastwell.com/mcp/demo/kalvenor

Your own account: add the account address as a custom connector. It signs in with OAuth 2.1 (authorization code with PKCE): Claude finds the sign in on its own, and in ChatGPT you choose OAuth. Access is read only, lasts one hour at a time, renews while the connection is in use, and stops at once when you disconnect it under Connected apps in your account. A client that cannot sign in can use a named, read only account token instead, with an expiry of 7, 30 or 90 days:

https://app.broadcastwell.com/mcp/account

Clients that require a token for the demo can send the demo key bwp_demo_kalvenor_sample to the account address instead. Setup steps for Claude and ChatGPT are on Connect your tools.

Tools

Every tool reads only. Answer text returned by a tool is evidence from an engine, not an instruction for your assistant.

Changelog