# Harvested verbatim from https://docs.brandfetch.com/openapi.json on 2026-08-14 (HTTP 200).
# Serialized JSON -> YAML with no content changes. Verbatim JSON: openapi/_original/brandfetch-api-openapi.json
openapi: 3.0.1
info:
title: Brandfetch API
description: Our APIs help you personalize your customer journey through unique branded experiences.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.brandfetch.io
paths:
/v2/brands/{identifier}:
get:
summary: Get brand data
description: Get brand data using a Domain, Brand ID, ISIN, Stock/ETF ticker, or Crypto symbol
operationId: getBrandData
tags:
- brands
security:
- bearerAuth: []
parameters:
- name: identifier
in: path
description: 'Identifier to retrieve brand data. Accepted formats:
- **Domain:** `nike.com`
- **Brand ID:** `id_0dwKPKT`
- **Stock or ETF ticker:** `NKE`
- **ISIN:** `US6541061031`
- **Crypto symbol:** `BTC`, `ETH`
**Note:** When using this generic endpoint, the identifier is resolved in the following order: `domain` → `ticker`
→ `isin` → `crypto`. To avoid naming collisions, use explicit type routes: `/v2/brands/{type}/{identifier}` where
`type` can be `domain`, `ticker`, `isin`, or `crypto`.'
required: true
schema:
type: string
examples:
domain:
summary: Domain
value: nike.com
brandId:
summary: Brand ID
value: id_0dwKPKT
ISIN:
summary: ISIN
value: US6541061031
stockSymbol:
summary: Stock or ETF ticker
value: NKE
cryptoSymbol:
summary: Crypto symbol
value: BTC
- name: allowNsfw
in: query
required: false
description: 'Brandfetch evaluates brands for NSFW content and reserves the right to not return inappropriate brands.
Depending on the severity, a brand may either not be returned at all (`404`), or be returned with its `isNsfw` property
set to `true`. The `allowNsfw` query parameter lets you control this behavior:
- **Not set** (default) — Some NSFW brands are not returned (`404`), others are returned with `isNsfw: true`.
- **`true`** — Returns the brand regardless of its NSFW status.
- **`false`** — Filters out all brands flagged as NSFW (returns `404`).'
schema:
type: boolean
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: <Not Found> or <Invalid Domain Name>
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found> or <Invalid Domain Name>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/brands/domain/{domain}:
get:
summary: Get brand data by domain
description: Get brand data using a domain name
operationId: getBrandDataByDomain
tags:
- brands
security:
- bearerAuth: []
parameters:
- name: domain
in: path
description: Domain name (e.g., `nike.com`)
required: true
schema:
type: string
examples:
domain:
summary: Domain
value: nike.com
- name: allowNsfw
in: query
required: false
description: 'Brandfetch evaluates brands for NSFW content and reserves the right to not return inappropriate brands.
Depending on the severity, a brand may either not be returned at all (`404`), or be returned with its `isNsfw` property
set to `true`. The `allowNsfw` query parameter lets you control this behavior:
- **Not set** (default) — Some NSFW brands are not returned (`404`), others are returned with `isNsfw: true`.
- **`true`** — Returns the brand regardless of its NSFW status.
- **`false`** — Filters out all brands flagged as NSFW (returns `404`).'
schema:
type: boolean
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: <Not Found> or <Invalid Domain Name>
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found> or <Invalid Domain Name>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/brands/ticker/{ticker}:
get:
summary: Get brand data by Stock or ETF ticker
description: Get brand data using a Stock or ETF ticker
operationId: getBrandDataByTicker
tags:
- brands
security:
- bearerAuth: []
parameters:
- name: ticker
in: path
description: Stock or ETF ticker (e.g., `NKE`, `QQQ`)
required: true
schema:
type: string
examples:
ticker:
summary: Stock or ETF ticker
value: NKE
- name: allowNsfw
in: query
required: false
description: 'Brandfetch evaluates brands for NSFW content and reserves the right to not return inappropriate brands.
Depending on the severity, a brand may either not be returned at all (`404`), or be returned with its `isNsfw` property
set to `true`. The `allowNsfw` query parameter lets you control this behavior:
- **Not set** (default) — Some NSFW brands are not returned (`404`), others are returned with `isNsfw: true`.
- **`true`** — Returns the brand regardless of its NSFW status.
- **`false`** — Filters out all brands flagged as NSFW (returns `404`).'
schema:
type: boolean
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: <Not Found>
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/brands/isin/{isin}:
get:
summary: Get brand data by ISIN
description: Get brand data using an ISIN code
operationId: getBrandDataByIsin
tags:
- brands
security:
- bearerAuth: []
parameters:
- name: isin
in: path
description: ISIN code (e.g., `US6541061031`)
required: true
schema:
type: string
examples:
isin:
summary: ISIN
value: US6541061031
- name: allowNsfw
in: query
required: false
description: 'Brandfetch evaluates brands for NSFW content and reserves the right to not return inappropriate brands.
Depending on the severity, a brand may either not be returned at all (`404`), or be returned with its `isNsfw` property
set to `true`. The `allowNsfw` query parameter lets you control this behavior:
- **Not set** (default) — Some NSFW brands are not returned (`404`), others are returned with `isNsfw: true`.
- **`true`** — Returns the brand regardless of its NSFW status.
- **`false`** — Filters out all brands flagged as NSFW (returns `404`).'
schema:
type: boolean
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: <Not Found> or <Invalid ISIN>
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found> or <Invalid ISIN>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/brands/crypto/{symbol}:
get:
summary: Get brand data by crypto symbol
description: Get brand data using a crypto symbol
operationId: getBrandDataByCrypto
tags:
- brands
security:
- bearerAuth: []
parameters:
- name: symbol
in: path
description: Crypto symbol (e.g., `BTC`, `ETH`). Uppercase preferred.
required: true
schema:
type: string
examples:
crypto:
summary: Crypto symbol
value: BTC
- name: allowNsfw
in: query
required: false
description: 'Brandfetch evaluates brands for NSFW content and reserves the right to not return inappropriate brands.
Depending on the severity, a brand may either not be returned at all (`404`), or be returned with its `isNsfw` property
set to `true`. The `allowNsfw` query parameter lets you control this behavior:
- **Not set** (default) — Some NSFW brands are not returned (`404`), others are returned with `isNsfw: true`.
- **`true`** — Returns the brand regardless of its NSFW status.
- **`false`** — Filters out all brands flagged as NSFW (returns `404`).'
schema:
type: boolean
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: <Not Found> or <Invalid Crypto Symbol>
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found> or <Invalid Crypto Symbol>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/search/{name}?c={clientId}:
get:
summary: Search brands
description: Search for brands by name, login to get a clientId
operationId: searchBrands
parameters:
- name: name
in: path
description: The name of the company you are searching for.
required: true
schema:
type: string
- name: c
in: query
description: A clientId is a unique identifier assigned to your application that allows it to authenticate and interact
with our service. [Get your client ID here](https://developers.brandfetch.com)
required: true
schema:
type: string
responses:
'200':
description: Returns brand data
content:
application/json:
schema:
type: array
items:
type: object
properties:
icon:
type: string
description: Brand icon URL
nullable: true
name:
type: string
description: Brand name
nullable: true
domain:
type: string
description: Brand website URL
nullable: false
claimed:
type: boolean
description: Set to true if the owner of the brand claimed its brand profile on [Brandfetch](https://brandfetch.com)
brandId:
type: string
description: Unique identifier for the brand
/v2/context/{domain}:
get:
summary: Get brand context by domain
description: Get a structured, narrative-rich brand context for a domain — including identity, positioning, voice, and
visual style.
operationId: getBrandContext
tags:
- context
security:
- bearerAuth: []
parameters:
- name: domain
in: path
description: Domain name (e.g., `brandfetch.com`)
required: true
schema:
type: string
examples:
domain:
summary: Domain
value: brandfetch.com
- name: cachedOnly
in: query
description: When `true`, return a brand context only if one is already cached, responding instantly without crawling
the domain. If no cached context exists, the API responds with `204 No Content` instead of resolving the domain
live (which can take several seconds). Useful for latency-sensitive use cases. Any value other than `true` (including
omitting the parameter) keeps the default behaviour of resolving the domain live on a cache miss. Defaults to `false`.
required: false
schema:
type: boolean
default: false
examples:
cachedOnly:
summary: Cached only (skip crawling)
value: true
responses:
'200':
description: 'Successful request. The response format is determined by the `Accept` header: `application/json` returns
a structured JSON object, while `text/markdown` returns the brand context as Markdown.'
content:
application/json:
schema:
$ref: '#/components/schemas/BrandContextResponse'
text/markdown:
schema:
type: string
description: The brand context rendered as Markdown.
'204':
description: Returned when `cachedOnly=true` and no brand context is currently cached for the domain. The response
body is empty. Because crawling is disabled there is nothing to return. Retry without `cachedOnly` to resolve
the domain live.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: Returned when the brand context could not be resolved. This may mean the domain was not found or is
invalid, or that we were unable to crawl the domain (e.g. due to DNS resolution issues, anti-botting protections,
or because the request could not be processed in the allotted time).
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- <Not Found> or <Invalid Domain Name>
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/brands/transaction:
post:
summary: Get brand data from a transaction
description: Turn payment transactions into merchant data
operationId: getBrandFromTransaction
tags:
- brands
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
transactionLabel:
type: string
description: The raw transaction text.
example: STARBUCKS 1523 OMAHA NE
countryCode:
type: string
description: An ISO 3166-1 alpha-2 country code indicating the country where the transaction took place.
example: US
required:
- transactionLabel
- countryCode
responses:
'200':
description: Successful request.
content:
application/json:
schema:
$ref: '#/components/schemas/BrandResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Not Found
'429':
description: API key quota exceeded
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- API key quota exceeded
/v2/viewer:
get:
summary: Get the authenticated viewer
description: 'Returns the identity of the credential used to authenticate the request: an API key or a user session
token (JWT). Use it to verify a credential during integration setup (a `200` response means the credential is valid;
`401`/`403` means it is missing, unknown, or revoked) and to display which API key and organization are connected.
Requests to this endpoint are free: they never consume API credits.'
operationId: getViewer
tags:
- viewer
security:
- bearerAuth: []
responses:
'200':
description: The presented credential is valid. The `type` property indicates which kind of credential authenticated
the request and determines the response shape.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ViewerApiKeyResponse'
- $ref: '#/components/schemas/ViewerUserResponse'
discriminator:
propertyName: type
mapping:
api-key: '#/components/schemas/ViewerApiKeyResponse'
user: '#/components/schemas/ViewerUserResponse'
examples:
apiKey:
summary: Authenticated with an API key
value:
type: api-key
id: id5ZQvmz9A
urn: urn:brandfetch:organization:cl5s9fps1275071ol9h7gs072m:api-key:id5ZQvmz9A
name: Production key
createdAt: '2026-05-12T09:14:07.000Z'
usage:
used: 1234
quota: 250000
organization:
id: cl5s9fps1275071ol9h7gs072m
urn: urn:brandfetch:organization:cl5s9fps1275071ol9h7gs072m
name: Acme Inc.
user:
summary: Authenticated with a user session token
value:
type: user
id: cl2xkl6h90007w135197r5abc
urn: urn:brandfetch:user:cl2xkl6h90007w135197r5abc
name: Jane Doe
email: jane@acme.com
createdAt: '2025-11-02T16:41:12.000Z'
'401':
description: Unauthorized. The Authorization header is missing or the credential could not be resolved.
content:
application/json:
schema:
type: object
properties:
message:
type: string
enum:
- Unauthorized
'403':
description: Forbidden. The credential was rejected, e.g. a revoked API key or an expired session token.
components:
schemas:
ViewerApiKeyResponse:
type: object
title: API key
description: The authenticated API key.
required:
- type
- id
- urn
- name
- createdAt
- usage
- organization
properties:
type:
type: string
enum:
- api-key
description: The kind of credential that authenticated the request.
id:
type: string
description: Id of the API key.
urn:
type: string
description: URN of the API key, e.g. `urn:brandfetch:organization:{organization.id}:api-key:{id}`.
name:
type: string
nullable: true
description: Display name of the API key, as set in the dashboard.
createdAt:
type: string
format: date-time
nullable: true
description: When the API key was created.
usage:
type: object
description: API credit consumption for the current billing period, mirroring the `x-api-key-quota` and `x-api-key-approximate-usage`
response headers of billable endpoints. Because this endpoint is free, `used` is the exact count, not approximated
one ahead like the header.
required:
- used
- quota
properties:
used:
type: integer
description: API credits consumed so far in the current billing period.
quota:
type: integer
description: API credit allowance for the current billing period.
organization:
type: object
description: The organization the API key belongs to.
required:
- id
- urn
- name
properties:
id:
type: string
description: Id of the organization.
urn:
type: string
description: URN of the organization, e.g. `urn:brandfetch:organization:{id}`.
name:
type: string
nullable: true
description: Display name of the organization.
ViewerUserResponse:
type: object
title: User
description: The authenticated user (dashboard session token).
required:
- type
- id
- urn
- name
- email
- createdAt
properties:
type:
type: string
enum:
- user
description: The kind of credential that authenticated the request.
id:
type: string
description: Id of the user.
urn:
type: string
description: URN of the user, e.g. `urn:brandfetch:user:{id}`.
name:
type: string
nullable: true
description: Full name of the user.
email:
type: string
nullable: true
description: Email address of the user.
createdAt:
type: string
format: date-time
nullable: true
description: When the user account was created.
Location:
type: object
description: Company's headquarter information
properties:
city:
type: string
description: Headquarter city
nullable: true
country:
type: string
description: Headquarter country
nullable: true
countryCode:
type: string
description: Headquarter country code (ISO 3166-1 alpha-2)
nullable: true
region:
type: string
description: Headquarter region
nullable: true
state:
type: string
description: Headquarter state
nullable: true
subregion:
type: string
description: Headquarter subregion
nullable: true
Industry:
type: object
properties:
id:
type: string
description: Unique identifier for the industry
score:
type: number
format: float
description: Score between 0-1 about the confidence in the industry
slug:
type: string
description: URL friendly identifier
name:
type: string
description: Name of the industry
emoji:
type: string
description: An emoji for the industry
parent:
description: If the object is a sub-category, the parent industry
items:
$ref: '#/components/schemas/IndustryParent'
nullable: true
IndustryParent:
type: object
properties:
id:
type: string
description: Unique identifier for the industry
slug:
type: string
description: URL friendly identifier
name:
type: string
description: Name of the industry
emoji:
type: string
description: An emoji for the industry
Format:
type: object
properties:
src:
type: string
description: File source
format:
type: string
enum:
- svg
- webp
- png
- jpeg
description: File format
height:
type: integer
nullable: true
description: File height in pixels
width:
type: integer
nullable: true
description: File width in pixels
size:
type: integer
description: File size in bytes
background:
type: string
enum:
- transparent
nullable: true
description: Indicates if the file has a transparent background
ErrorResponse:
type: object
properties:
message:
type: string
enum:
- Error message.
BrandResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the brand
nullable: false
name:
type: string
description: Brand name
nullable: true
domain:
type: string
description: Brand website URL
nullable: false
claimed:
type: boolean
description: Set to true if the owner of the brand claimed its brand profile on [Brandfetch](https://brandfetch.com)
nullable: false
description:
type: string
description: Brand description
nullable: true
longDescription:
type: string
description: Brand long description
nullable: true
links:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the social media platform
nullable: false
enum:
- twitter
- facebook
- instagram
- github
- youtube
- linkedin
- crunchbase
url:
type: strin
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brand-api/refs/heads/main/openapi/brand-api-brandfetch-openapi.yml