Brand API endpointsBeta

Every Brand API endpoint with its scope, what it returns and the fields of a brand.

Updated Oct 27, 20263 min read

Beta. The Brand API is in beta. Fields can still be added to version 1, and any breaking change will ship as a new version (/api/v2) rather than change v1.

All paths are under /api/v1. {brand} is the brand's id (uuid) or its slug. A brand from another workspace returns 404, the same as one that does not exist.

Endpoint	Scope	What it does
`GET /brands`	`brands:read`	Your workspace's brands, newest first. Accepts `limit` and `cursor`.
`GET /brands/{brand}`	`brands:read`	One brand in full.
`PATCH /brands/{brand}`	`brands:write`	Change a brand. See Update a brand through the API.
`GET /brands/{brand}/assets`	`brands:read`	Logos, icon, banner and collection files, each with a short-lived `download_url`.
`GET /brands/{brand}/markdown`	`brands:read`	The brand's `brand.md` as `text/markdown`. Works for draft and private brands.
`GET /brands/{brand}/analytics`	`brands:read`	Views, downloads and requests. `period` is `30d` (default), `90d` or `all`.
`GET /brands/{brand}/requests`	`brands:requests`	People who asked for access. Filter with `status` (`pending`, `approved`, `rejected`).
`POST /brands/{brand}/requests/{request}`	`brands:requests`	Approve or reject a request. See Manage access requests through the API.

The list response

GET /brands returns data, an array, and next_cursor. Each item has id, slug, name, summary, access, is_draft, download_approval, indexable, created_at and urls (the public page address and the api address of that brand).

Fields of a brand

GET /brands/{brand} returns these fields.

Field	Contents
`id`, `slug`, `name`	The brand's identifiers and name.
`summary`, `story`	Short description and longer story, as text.
`industry`, `size`, `company_type`, `year_founded`	Company facts, as text.
`website`	The brand's website address.
`social`	`twitter`, `facebook`, `instagram`, `linkedin`, `youtube` and `github` links.
`colors`	`primary`, `secondary` and `additional` (a list of `name` and `value`).
`fonts`	`headline` and `body`, each with `name` and `custom`, or `null`.
`access`	`public`, `password` or `restricted`.
`is_draft`, `download_approval`	Whether the brand is a draft, and whether downloads need your approval.
`indexable`	True when the page is public and not a draft, so search engines may list it.
`tracking`	`ga4`, `gtm` and `search_console` IDs.
`seo`	`title` and `description` for search results, or `null`.
`team`	A `title` and a list of members with `name` and `title`.
`press`	Links with `title`, `url` and `source`.
`urls`	`page`, `markdown`, `mark_usage` and `api` addresses.
`created_at`	When the brand was created.

Files

GET /brands/{brand}/assets returns images (icon, main logo and banner, each with a role), logos, and collections with their files. Every file has a download_url. These links expire, so fetch a file soon after you list it and ask again when you need a fresh link. The response includes links_expire: true as a reminder.

Analytics

GET /brands/{brand}/analytics returns period, then views, downloads and requests. Each has a total and a series over time (daily, or monthly for all). These are the same numbers shown on the brand's overview in your dashboard.

Brand API endpointsBeta

The list response

Fields of a brand

Files

Analytics

More in Developers

Brand API errors, paging and rate limits

Brand API overview

Brand API quick start

Manage access requests through the API

Update a brand through the API