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. Message 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, check_ai_visibility, run_review_mirror, panel_run, panel_list, panel_get, prospect_run, prospect_list_review, prospect_review, assessment_watch, assessment_list, assessment_deltas, 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 an Intel loop 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.

Every figure carries its provenance

Provenance is part of the API contract. 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.

Failures follow the same rule. 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