# Brand Studio

> Brand Studio turns your brand's whole online presence into context — so you,
> and the tools you work with, can create on your brand's behalf. That only
> works if every fact is right. So every fact here carries its receipt.

Brand Studio runs fourteen checks against one URL — website, search, social,
SEO, reputation, ads, logos, colors, typography, voice, AI visibility,
reviews, and backlinks — and returns a report where every claim traces back
to evidence, or says plainly that it has none. A section with no data renders
as absent, never as a fabricated zero.

In the beta: accounts are free and the signup page says how first credits are
granted; reports cost 1 to 3 credits by depth (Snapshot, Market or Deep); a
report that produces no evidence is never charged. Card checkout is not
connected, and bring-your-own provider keys are not enabled on the hosted
version. AI visibility is parked. DataForSEO supplies the search data for paid
reports and the beta weekly search check; its AI lanes stay parked, and the
free read never calls it.

## Documentation

- [Documentation index](/docs): every provider called, every check a report
  runs, what each costs, and how to run the whole thing yourself.
- [Quick start](/docs/quick-start): the hosted version or self-hosting (your
  own keys on the hosted version are not enabled in the alpha).
- [How it works](/docs/how-it-works): the pipeline, end to end, as a diagram.
- [What the report contains](/docs/report): all fourteen checks, one page
  each.
- [The APIs, in depth](/docs/providers): every outside party this product
  calls.
- [Where a model touches your report](/docs/models): every model call, what
  it may and may not do.
- [Run it yourself](/docs/open-source): every environment variable, and what
  it turns on.
- [For agents](/docs/for-agents): this file's long form — service-account
  keys, the MCP endpoint, its tools, and the versioning promise below.

## For agents

- MCP endpoint: `POST /api/mcp` — Streamable HTTP, JSON-RPC 2.0
  (`initialize`, `tools/list`, `tools/call`). No session id, no SSE; every
  call is a standalone POST.
- Auth: `Authorization: Bearer ...` with either a service-account API key
  (`bsk_live_...`) or the token an assistant receives when it connects
  through OAuth (Claude or ChatGPT; setup on /mcp). An OAuth assistant is
  read-only. Keys are issued from the account's API keys page (`GET/POST/DELETE
  /api/account/api-keys`, signed-in session required to manage keys — a key
  cannot create or revoke its own siblings). Each key carries `name`,
  `scopes` (`run_pulls`, `read_reports`), `last_used_at`, and `revoked_at`.
  Only its SHA-256 hash is ever stored; the plaintext is shown exactly once,
  at creation.
- Tools that read (scope `read_reports`): `list_brands`,
  `get_brand_basics`, `get_brand_changes`, `list_brand_changes`,
  `get_site_pages`, `get_social_changes`, `get_search_changes`,
  `get_brand_monitoring`, `list_brand_reports`,
  `get_brand_report_overview`, `get_brand_report_section`,
  `get_brand_media`, `open_brand_report`, `get_brand_report_view_chunk`,
  `get_pull_status(pull_id)`, `get_brand_report(pull_id)` and
  `get_brand_kit(pull_id)`.
- Tools that quote or run a pull (scope `run_pulls`): `quote_brand_pull`
  and `run_brand_pull(url, pull_plan, seo_market, plan_bindings, plan_hash,
  approved_max_cost_usd, tier?, idempotency_key?)`. Quote first; run with the
  exact reviewed plan. Each tool is a thin wrapper over the same handlers the
  hosted UI calls — no separate code path, no separate truth.
- Idempotency: `run_brand_pull`'s optional `idempotency_key` is unique per
  account. A retry with the same key returns the ORIGINAL pull — same
  `pull_id`, HTTP 200, never a second charge — instead of starting a new one.
  Built for exactly the caller an MCP tool attracts: an agent that retries on
  timeout while the pull is still completing on our clock.
- Errors are honest, not generic. Insufficient credits names the shortfall
  and which tier IS affordable; a scope error names the missing scope
  (`required_scope`) rather than returning a bare "forbidden".
- The versioning promise: every report response carries
  `contract_version: "brand-studio-report/v1"`. A breaking change to that
  envelope's shape ships as `v2` with a deprecation window, never as a silent
  edit under a consumer already depending on `v1`.

## Optional

- [Changelog](/docs/changelog): what changed in these documents, and when.