---
title: "Brand API endpoints"
description: "Every Brand API call with its scope, parameters and what it returns."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/api)). The exact request and response schemas are in [`openapi.json`](https://tarkle.com/api/v1/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. |
| `POST /brands` | `brands:create` | Add a brand (a private draft). See [Create, delete and restore brands](/docs/api/brands/create-and-delete). |
| `PATCH /brands/{brand}` | `brands:write` | Change a brand. See [Update a brand](/docs/api/brands/update-a-brand). |
| `DELETE /brands/{brand}` | `brands:create` | Move a brand to the bin. Needs `confirm_delete: true`. |
| `GET /deleted-brands` | `brands:create` | The brands in the bin that can still be restored. |
| `POST /deleted-brands/{brand}/restore` | `brands:create` | Put a deleted brand back. |
| `POST /brands/{brand}/files` | `brands:files` | Start an upload. See [Upload brand files](/docs/api/brands/files). |
| `POST /brands/{brand}/files/{file}/complete` | `brands:files` | Check the uploaded file and attach it. |
| `GET`, `PUT`, `DELETE /brands/{brand}/domain` | `brands:domains` | Check, connect and remove the brand's domain. See [Brand domains](/docs/api/brands/domain). |
| `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](/docs/api/brands/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.

## Related

- [Quick start](/docs/api/brands/quick-start)
- [Paging and limits](/docs/api/paging-and-limits)
- [Errors](/docs/api/errors)

Source: https://tarkle.com/docs/api/brands/endpoints/index.mdx