Brand API endpoints

Paths are relative to https://tarkle.com/api/v1. Every call sends Authorization: Bearer tk_... and X-Workspace-Key: <key> (see the API overview). The exact request and response schemas are in openapi.json.

{brand} is the brand’s id (a uuid) or its slug. A value that is neither answers 400. A brand in another workspace answers 404.

Calls

Call	Scope	What it does
`GET /brands`	`brands:read`	The workspace’s brands, newest first. `limit` (1 to 100, default 25) and `cursor`.
`GET /brands/{brand}`	`brands:read`	One brand in full.
`PATCH /brands/{brand}`	`brands:write`	Change a brand. See Update a brand.
`GET /brands/{brand}/assets`	`brands:read`	Logos, icon, banner and collection files with short-lived download links.
`GET /brands/{brand}/markdown`	`brands:read`	The brand as `brand.md` (`text/markdown`).
`GET /brands/{brand}/analytics`	`brands:read`	Views, downloads and requests. `period` is `30d` (default), `90d` or `all`.
`GET /brands/{brand}/requests`	`brands:requests`	Download and view requests. `status`, `limit`, `cursor`.
`POST /brands/{brand}/requests/{request}`	`brands:requests`	Approve or reject one request. See Access requests.

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).

Fields of a brand

GET /brands/{brand} returns these fields. Text fields come back as an empty string when they are not set, not null.

Field	Contents
`id`, `slug`, `name`	The identifiers and the name.
`summary`, `story`	Short description and longer story.
`industry`, `size`, `company_type`, `year_founded`	Company facts.
`website`	The brand’s website address.
`social`	`twitter`, `facebook`, `instagram`, `linkedin`, `youtube` and `github` links.
`colors`	`primary` and `secondary` (or `null`) 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 approval.
`indexable`	True when the page is public and not a draft.
`tracking`	`ga4`, `gtm`, `search_console` and `adobe_kit` IDs.
`seo`	`title` and `description`, each `null` when not set.
`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 brand (id, slug), then images, logos and collections.

images lists the icon, main logo and banner that are set, each with a role of icon, main_logo or banner.
logos lists the other logos with id, name, type and download_url.
collections lists each collection with id, name, description and files. Each file has id, name, type, size and download_url.

Download links expire. The response carries links_expire: true, so list again when you need a fresh link.

Analytics

GET /brands/{brand}/analytics returns period, then views, downloads and requests, each with a total and a series. 30d and 90d give one point per day, all gives one per month. The series is built from the 2,000 most recent rows of each number, so for a very busy brand it can add up to less than its total.

The numbers cover only the brand in the path. The Brands page in the dashboard adds all brands together.