The Audience Intel engine, inside your own tooling.

Quickstart

1 · Get a key. There is no self-serve signup: API and MCP access is the Enterprise tier (price on application), and keys are minted by the operator after a conversation about scopes and spend caps. Email us to start. Keys look like aik_live_… and are shown exactly once at mint — only a SHA-256 hash is stored, so a lost key is a re-mint, not a recovery.

2 · Authenticate. Every request sends the key as a Bearer token. Prove yours works:

curl https://audienceintel.app/api/v1/health \
  -H "Authorization: Bearer aik_live_..."

# → { "ok": true, "client": "Your Firm", "scopes": ["read:reports", ...] }

3 · First calls. List reports, then pull the fact layer with a provenance filter — note every fact carries provenance, confidence and truth-gate status:

curl "https://audienceintel.app/api/v1/reports?limit=5" \
  -H "Authorization: Bearer $KEY"

curl "https://audienceintel.app/api/v1/reports/$REPORT_ID/facts?provenance=measured" \
  -H "Authorization: Bearer $KEY"

4 · Connect an AI client over MCP. The remote MCP server lives at https://audienceintel.app/api/mcp (Streamable HTTP, stateless) and shares the same key auth — the key needs the mcp:connect scope, and each tool additionally enforces its own scope from the table below. For Claude Code:

claude mcp add --transport http audience-intel \
  https://audienceintel.app/api/mcp \
  --header "Authorization: Bearer aik_live_..."

For Claude.ai (Team/Enterprise custom connectors) or any other MCP client: remote server URL https://audienceintel.app/api/mcp with an Authorization: Bearer aik_live_… header. Tools exposed: run_market_scan, list_reports, get_report, query_report_facts, correct_fact, run_review_mirror, check_ai_visibility, mint_teaser_links, check_outreach_eligibility, get_funnel_stats. Tools that spend money say so in their descriptions, so your model will warn you before it runs one.

Scopes

Every key carries an explicit scope list; every endpoint declares what it needs (also machine-readable in the spec as x-required-scopes). Spend-triggering scopes are never granted by default and are inert until the key also has a daily spend cap above zero.

Spend caps

Some operations spend real money — paid data connectors, LLM legs, Prolific panel budgets. Each key has a dailySpendCapPence (UTC day). Before a spend operation dispatches, its estimated cost is checked against the cap and written to an append-only ledger — admission-time accounting, so a crashed job still counted and a refusal happens before anything upstream is touched. Over the cap answers 403 spend_cap_exceeded with capPence, spentPence and estimatePence in the details, and every successful spend response echoes the same accounting. A cap of 0 makes spend scopes unusable even if granted.

The operations that spend:

• POST/api/v1/scans — Enqueue a full market scan. SPEND — admitted against the key's daily cap.
• POST/api/v1/prospect-runs — Run a prospect console run. SPEND — answers 202, then poll.
• POST/api/v1/mirror/analyses — Run a Market Mirror review analysis. SPEND — answers 202, then poll.
• POST/api/v1/dev/scrape — Forward a Firecrawl scrape through the Fly proxy. SPEND. Dev only.
• POST/api/v1/dev/llm — Forward a structured LLM completion through the Fly proxy. SPEND. Dev only.
• POST/api/v1/validation/studies/{id}/publish — Publish the study to Prolific. THE money step — two independent gates.

POST /api/v1/scans/estimate is the free pre-flight: it prices a scan, a mirror run, or a prospect run (per-source) in pence so you can check against your cap before committing. Validation publishing is additionally protected by a global spend guard on our side — two independent gates, both required.

Honest data, by contract

The discipline behind the reports is part of the API surface, not marketing. Every fact and figure that leaves this API carries a provenance label: measured (observed directly — a real query against a live engine, a registry read, a crawled page), inferred (derived from measured inputs), modelled (estimated from priors, labelled as such), or supplied (stated by the client, never verified by us) — plus a confidence figure and a truth-gate status (unverified / verified / corrected / rejected) from operator QA. No endpoint strips these to make a response cleaner, and the derivation graph (GET /reports/{id}/graph) shows how every derived number traces back to its inputs.

The same honesty applies to failure. A missing upstream or a dead dependency answers { ok: false, reason: … } or a typed error envelope — never an invented number, never a padded count, never a stack trace. If GET /api/v1/statscan't reach the database, it says so; it does not guess.

One error envelope

Every error is { ok: false, error: { code, message, details? } } with a machine-stable code. Auth fails closed (a database error during key lookup is a 503, never an allow-through); rate limiting fails open (a broken counter must not take the API down).

Within v1, changes are additive only — new fields, new endpoints, new output enum values. Renames, removals or new required inputs would be a v2.

Endpoint reference

Generated from the same document served at /api/v1/openapi.json (OpenAPI 3.1, public, no key required) — point your client generator at that. Base URL: https://audienceintel.app/api/v1.

Enterprise — price on application

API and MCP access ships as the Audience Intel Enterprise tier, for firms and agencies running the engine across a portfolio: API access to the report engine, an MCP server so your own AI tools can query your market data directly, and a named client success manager. Scoped and priced to your estate — keys, scopes, rate tiers and spend caps are agreed in a conversation, not a checkout.

Audience Intel · part of Bridge Intelligence · by Cambray Design · audienceintel.app