- 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.
Make your first request
The Brand Context API uses the same API key as the Brand API. Requests forbrandfetch.com are free, so you can build without spending quota:
Accept: text/markdown. See content negotiation.
Query by domain
You query the Brand Context API by a domain name, or by a website URL or email address on the domain: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 theAccept 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, addcachedOnly=true. The API then returns a context only if one already exists, and answers 204 No Content otherwise, without resolving the domain:
cachedOnly populates the cache. Real-time indexing covers when to use each.
Response shape
When requestingtext/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.meta
meta
On a cached response,
resolved_at is when the context was originally resolved, not when you made the request.identity
identity
positioning
positioning
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.brand
brand
style describes the visual identity in prose. For logo files, color values, and font names, use the Brand API.competition
competition
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.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 thex-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.