# brandcurl

Input a public brand domain or HTTP(S) URL and get deterministic brand
intelligence: evidence-backed logos, colors, typography, imagery, and company
metadata. Core extraction does not require AI.

## Base URL

https://brandcurl.com

## Authentication

Hosted /v1 endpoints take a Bearer token. Create one at the site: sign in →
Dashboard → API keys. Keys look like `bc_live_…`. Self-hosted
development can explicitly run without authentication.

    Authorization: Bearer bc_live_your_key

Store the key server-side as `BRANDCURL_API_KEY`. Never put it in a URL,
browser bundle, generated asset, log, or repository. The official local MCP
adapter also accepts the older `BRANDCURL_KEY` name for compatibility.

## REST endpoints

- `GET  /v1/brands/{domain}`          Canonical brand profile
- `POST /v1/brands/{domain}/refresh`  Idempotent asynchronous refresh
- `GET  /v1/logo/{domain}`            Selected logo bytes; params: type, theme, variant, format
- `GET  /v1/search?q=&limit=`          Search indexed brand records
- `GET  /v1/enrichments/{domain}`      Cached generic company enrichment
- `POST /v1/enrichments/{domain}/refresh`  Refresh company enrichment with BYOK providers
- `GET  /v1/jobs/{id}`                 Poll asynchronous jobs
- `POST /v1/research/{domain}`         Optional experimental AI research

Query parameters are strict: unknown/repeated keys and invalid values return
`400 invalid_parameter`. Every v1 response includes `X-Request-ID`;
rate-limited clients must respect `Retry-After`. Treat job IDs as opaque.
For GET responses, persist the body with its `ETag` and send
`If-None-Match` on the next read. Reuse the persisted body when the API
returns an empty `304`; 304 responses are not charged. Inspect
`X-Cache`, `RateLimit-*`, and `X-Balance-Remaining`.
Use an 8–200 character `Idempotency-Key` when starting a brand refresh;
it is required for company enrichment because provider calls may consume credits.
Enrichment supports request-scoped `X-Apollo-Key`, `X-Lusha-Key`,
and `X-Gemini-Key`. Use `?providers=apollo,lusha,gemini` as a
strict cost-control allowlist. Any caller-key enrichment stays on its
owner-scoped job and never enters the shared enrichment cache. Caller-key
operations require an authenticated principal. Research accepts request-scoped
`X-OpenRouter-Key` at the discounted BYOK posted price. Caller-key
research remains on its owner-scoped job and never enters the shared brand
cache. Send provider keys only from server-side code.

Use the ordinary brand GET for colors, logos, fonts, and basic company fields.
Do not automatically escalate a sparse response into refresh, context refresh,
enrichment refresh, or research: those are distinct paid products. Contexts are
optional materialized messaging intelligence; enrichment is separate
source-attributed firmographics.

Small machine-readable contract: https://brandcurl.com/docs/contract.md
OpenAPI spec: https://brandcurl.com/v1/openapi.yaml — human docs: https://brandcurl.com/docs

    curl -H "Authorization: Bearer bc_live_…" https://brandcurl.com/v1/brands/atomicwings.com

## Managed company and people API

Use a Brandcurl account key; Brandcurl supplies the upstream credentials.
Start with `GET /v1/data/capabilities` for enabled operations, exact
maximumUnitCharge, priceVersion, supportedFilters and limits. Disabled/unpriced
purchases return 503 without charging. The complete 18-route contract is at
https://brandcurl.com/v1/data/openapi.json, with the billing/retry guide at
https://brandcurl.com/docs/contract.md#company-and-people-data.

Company/people enrichment and bulk enrichment, company/people search and details,
company jobs/news, native email reveals, free company projections and tenant-owned
job status/results are covered. All POSTs require Idempotency-Key; use it on paid
GETs too. Enrichment/reveals also require maxCharge and return an async job.
Poll to settlement and inspect per-item outcomes. A 402 includes balanceUsd,
priceUsd and topUpUrl; top up and retry the same denied key. A failed supplier
purchase replays without buying again. Managed responses are private, no-store;
ETag/304 caching applies to the brand API, not managed purchases. Expanded data
operations currently use REST; the four MCP tools below retain their existing scope.

## MCP

brandcurl is an MCP server. Tools: `extract_brand`, `get_logo`, `search_brands`, `get_company_enrichment`.
The hosted endpoint is sessionless Streamable HTTP, supports the current MCP protocol plus legacy clients, and all tools are read-only.

Remote (HTTP) — nothing to install:

    {
      "mcpServers": {
        "brandcurl": {
          "type": "http",
          "url": "https://brandcurl.com/mcp",
          "headers": { "Authorization": "Bearer bc_live_…" }
        }
      }
    }

Codex (remote, with `BRANDCURL_API_KEY` exported before Codex starts):

    [mcp_servers.brandcurl]
    url = "https://brandcurl.com/mcp"
    bearer_token_env_var = "BRANDCURL_API_KEY"
    tool_timeout_sec = 60

Local (stdio, installed from GitHub Packages after configuring npm authentication):

    {
      "mcpServers": {
        "brandcurl": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@cglabs-ai/brandcurl-mcp"],
          "env": { "BRANDCURL_API_KEY": "bc_live_…" }
        }
      }
    }

The stdio adapter is published to GitHub Packages as `@cglabs-ai/brandcurl-mcp`.
Configure the `@cglabs-ai` scope for `https://npm.pkg.github.com` and authenticate with a token carrying `read:packages`.
Use remote HTTP MCP unless you specifically need a local process.

## Put this brief where your tool reads it

| Tool           | File it reads |
|----------------|-------------------------------------|
| Claude Code    | `AGENTS.md` / a `.claude` skill |
| Cursor         | `.cursor/rules/brandcurl.mdc` |
| Codex          | `AGENTS.md` + `config.toml` MCP block |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Windsurf       | `.windsurf/rules/brandcurl.md` |
| Cline          | `.clinerules` |
| Gemini CLI     | `GEMINI.md` |

Same content, different filename — it all points back to this brief: https://brandcurl.com/AGENTS.md