---
title: "Brand API"
description: "Read and change Tarkle brand pages from your own code, and handle access requests."
---

> 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

The Brand API reads and changes the [brand pages](https://tarkle.com/help/branding/what-is-a-brand-page) of a workspace, one request at a time. It is part of the Tarkle API at `https://tarkle.com/api/v1`. Start with the [API overview](/docs/api) for tokens, workspace keys and rate limits.

## What you can do

- **List brands.** Name, summary, access, links, newest first, 25 at a time. Page with `limit` and `cursor`.
- **Read one brand.** Text, facts, social links, colors, fonts, access, tracking IDs, SEO fields, team and press.
- **Get its files.** Logos, icon, banner and collection files, each with a short-lived download link.
- **Get `brand.md`.** The brand as one Markdown document, the form AI assistants read best.
- **Read page views, downloads and requests.** For 30 days (default), 90 days or all time.
- **Update a brand.** Text, links, primary color, access, download approval, draft state and tracking IDs. See [Update a brand](/docs/api/brands/update-a-brand).
- **Create, delete and restore brands.** A new brand is a private draft; a deleted brand goes to the bin and can come back for 30 days (Free) or 90 days (Pro and Agency). See [Create, delete and restore brands](/docs/api/brands/create-and-delete).
- **Upload files.** Icon, logos, banner, social image, favicon and collection files, checked like the brand editor does. See [Upload brand files](/docs/api/brands/files).
- **Connect a domain.** Connect, check and remove a brand's own domain with the plan rules of the app. See [Brand domains](/docs/api/brands/domain).
- **Get events.** Receive signed [webhooks](/docs/api/webhooks) when a brand is viewed, downloaded, updated or asked for access.
- **Handle access requests.** List the people who asked to download or view a brand, then approve or reject each one. See [Access requests](/docs/api/brands/access-requests).

## Which brands a token reaches

A token belongs to a person and works for every workspace that person can use. You name the workspace on each call with `X-Workspace-Key`. Inside it, the brand endpoints need the token's creator to be an **owner or admin** of that workspace, and the token needs the scope for the call:

| Scope | Allows |
| --- | --- |
| `brands:read` | Read brands, their assets, `brand.md` and analytics |
| `brands:write` | Update a brand's text, links, access and settings |
| `brands:create` | Create brands, delete them to the bin, list the bin and restore from it |
| `brands:files` | Upload a brand's icon, logos, banner, social image, favicon and collection files |
| `brands:domains` | Connect, check and remove a brand's custom domain |
| `brands:requests` | List download and view requests and approve or reject them |

A token with no scopes can do nothing. A brand in another workspace answers `404 not_found`, the same as a brand that does not exist.

The API is for servers. It has no CORS support, so a token in browser code is a leaked token.

## What it cannot do yet

- Set a password. `access` accepts only `public` or `restricted`; making a brand public removes its password and needs `confirm_public: true`.
- Change a brand's slug, secondary color, additional colors, fonts, team members or press.
- Remove a file, or upload team photos, guideline images or fonts.
- Send webhooks for creating, deleting or restoring a brand, or for domain changes.

## Machine-readable description

`GET https://tarkle.com/api/v1/openapi.json` is an OpenAPI 3.1 file with typed schemas for every brand call. It needs no token.

## Next

- [Quick start](/docs/api/brands/quick-start)
- [Endpoints](/docs/api/brands/endpoints)
- [Idempotency keys](/docs/api/idempotency)
- [Paging and limits](/docs/api/paging-and-limits)

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