Skip to main content
The Brand Context API returns what a language model needs to know about a company before it writes for it, sells to it, or talks about it. A logo and a hex code tell a model what a brand looks like. They do not tell it what the company sells, who buys it, or how it talks. For each domain, the API returns four sections:
  • Identity: tagline, mission, description, and tags.
  • Positioning: value proposition, target audience segments, and products and services, each with its category, features, and published pricing where the brand’s site states them.
  • Brand: a summary of the brand’s voice and visual style, with descriptive attributes.
  • Competition: up to five named competitors, each with its domain and where it competes with the brand.
Brands that are not in the dataset yet are resolved live, so coverage is not limited to a fixed list. See real-time indexing.

Make your first request

The Brand Context API uses the same API key as the Brand API. Requests for brandfetch.com are free, so you can build without spending quota:
To put the context straight into a prompt, ask for Markdown instead with Accept: text/markdown. See content negotiation.
Building an agent with no account? It can pay per request with x402 or MPP instead of using an API key.

Query by domain

You query the Brand Context API by a domain name, or by a website URL or email address on the domain:
The API resolves an email address to its registrable domain before the lookup. john@example.brandfetch.com returns the same context as brandfetch.com. The API does not store the address. Your request logs show only the domain. The API resolves a website URL to the registrable domain of its host before the lookup. https://www.brandfetch.com/developers/pricing returns the same context as brandfetch.com. The API does not store the URL. Your request logs show only the domain. If you only have company names, use the Brand Search API to match brand names to the most likely domains first.

Content negotiation

The Brand Context API supports content negotiation. Use the Accept request header to choose the format of the response:
  • application/json (default): returns the structured JSON object described below.
  • text/markdown: returns the brand context as a Markdown document, ready to drop directly into an LLM prompt or a Markdown-aware surface.

Skip crawling (cached only)

A live resolution can take several seconds. For latency-sensitive uses, such as an interactive frontend, add cachedOnly=true. The API then returns a context only if one already exists, and answers 204 No Content otherwise, without resolving the domain:
A standard request without cachedOnly populates the cache. Real-time indexing covers when to use each.

Response shape

When requesting text/markdown, the response is a Markdown document covering the same information. When requesting application/json, the response is grouped into a few top-level objects: meta, identity, positioning, brand and competition are present on every 200 response, and the arrays in the first four come back empty rather than null when there is nothing to report. The optional product fields and competition are the exception: their keys are always present, but their values are null when the brand’s site does not support them, and on a context generated before they were added. Such contexts are regenerated over time.
Unlike the rest of the Brandfetch API, which uses camelCase, the Brand Context API returns field names in snake_case (for example canonical_name, value_proposition, products_and_services) to align with conventions commonly used by the LLM tooling that consumes this data.
On a cached response, resolved_at is when the context was originally resolved, not when you made the request.
Every product or service also carries these keys. A value is null when the brand’s site does not state it (array fields may be an empty array instead, which means the same), and no value is ever guessed.
style describes the visual identity in prose. For logo files, color values, and font names, use the Brand API.
An empty competitors array means no competitor could be identified, which is common for small and local businesses. Pass a competitor’s domain to the Brand API for its logos and colors.
Every field, with its type, is listed in the API Reference. The Markdown representation is served as text/markdown; charset=utf-8. It opens with the brand’s canonical name as a heading, followed by the domain and the resolution timestamp, and then covers the same sections in the same order: identity, positioning (value proposition, target audience, products & services), brand voice and style, and competition. Fields with no value are omitted rather than rendered empty.
A cachedOnly=true request that finds nothing cached returns 204 No Content with an empty body, whichever format you asked for, so check the status code before parsing the response.

Errors

A live resolution usually completes within the request. When it does not, or when no context can be generated, the status code and the x-bf-error header say what happened and whether retrying helps. None of these responses is charged. A request paid with x402 or MPP can also receive a 503 without an x-bf-error header. That one comes from the payment service; see Pay per request for how to retry it.

Quotas and usage

The Brand Context API shares one quota with the Brand API and Transaction API, counted in brand fetches. See limits and billing for quotas, throughput, and overage.

API Reference

For more details, refer to our API Reference.