---
title: "Brand API"
description: "Read, create, change, archive and restore Tarkle Brand Pages from your own code with an API key, 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 the shared rules, and read [Authentication](/docs/get-started/authentication) to see how your API key is sent.

## What you can do

- **List brands.** Name, summary, access, links and draft state, newest first. The default page holds 25 brands, and `limit` can ask for up to 100.
- **Read one brand.** Text, facts, social links, colors, fonts, access, tracking IDs, SEO fields, team, press and guidelines.
- **Get its files and brand.md.** `GET /brands/{brand}/assets` lists the icon, logos, banner and collection files, each with a short-lived download link. `GET /brands/{brand}/markdown` returns the brand as `brand.md`.
- **Read page views, downloads and requests.** `period` is `30d` (default), `90d` or `all`.
- **Update a brand.** Text, links, colors, fonts, team, press, guidelines and access. See [Update a brand](/docs/api/brands/update-a-brand).
- **Create, archive and restore brands.** A new brand is a private draft. Deleting a brand archives it, and an archived brand can be restored. See [Create, delete and restore brands](/docs/api/brands/create-and-delete).
- **Upload, import and remove files.** Icon, logos, banner, social image, favicon and collection files, plus team photos and guideline images. See [Upload brand files](/docs/api/brands/files).
- **Connect a domain.** Connect, check and remove a brand's own domain. See [Brand domains](/docs/api/brands/domain).
- **Look up a brand from a website.** `POST /brand-lookup` returns suggested details and pictures for a website address and saves nothing.
- **Get events.** Signed [webhooks](/docs/api/webhooks) for brand views, downloads, updates and access requests. Views are sent only to endpoints that ask for them.
- **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).

## Keys and workspaces

Send your API key on every call as `Authorization: Bearer <your-tarkle-key>`. Owners and admins of an organization create keys in Settings, API. A key can do everything the API can, in the workspaces it reaches, and it acts as the person who made it. The one thing a key cannot do is make a purchase.

A key limited to chosen workspaces answers `403 no_access` for any other workspace. Name the workspace on every call with the `X-Workspace-Key` header, which takes the 8-character workspace key, not its id. An id is refused with `400 workspace_key_required`. Only `GET /workspaces` works without it.

Brand endpoints also need the key's creator to be an owner or admin of that workspace. A brand of another workspace answers `404 not_found`, the same as a brand that does not exist.

Each endpoint checks one internal scope: `brands:read` to read, `brands:create` to create, archive and restore, or `brands:files` to upload and remove files. A key holds all of them, so you never choose them. A key that lacks the scope a call needs answers `403 forbidden`.

```bash
curl -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $WORKSPACE_KEY" https://tarkle.com/api/v1/brands
```

Keep the key on your server. Never put it in browser code or a public repository.

## Create a brand

`POST /brands` adds a brand as a private draft. `name` is required, and so are `summary` and `industry`. At the plan's brand page limit the call answers `403 forbidden`, and a slug already used in the workspace answers `409 name_taken`.

Send `password` to protect the brand from the start. It must be at least 8 characters. Setting a password on create is API only: the MCP server cannot set one.

## Archive and restore

`DELETE /brands/{brand}` archives a brand instead of deleting it for good. The page goes offline and answers `404`, the app stops listing it, its address (slug) and its place under the plan's brand page limit are freed, and its domains are detached. The brand, its files and its settings are kept with no time limit. Access requests, analytics and the kit link are not kept. The call needs `confirm_delete: true`, in the query or the body, otherwise it answers `400 confirmation_required`.

`GET /archived-brands` lists the archived brands of the workspace, newest first. `POST /archived-brands/{brand}/restore` puts one back with the same id and content, using the id from that list. It counts toward the plan's brand page limit, so it answers `403 forbidden` at the limit. If the address is taken now, send another `slug` in the body, otherwise the call answers `409 name_taken`. Domains are not restored; connect them again with [Brand domains](/docs/api/brands/domain).

## Files and pictures

Upload a brand file in two steps. `POST /brands/{brand}/files` returns a signed upload address, and you complete the upload with the file id. `POST /brands/{brand}/files/import` does both steps in one call for a public https image address. Remove a file with `DELETE /brands/{brand}/files?slot=...`. See [Upload brand files](/docs/api/brands/files).

Team photos and guideline images can be given as public https addresses too, as `photo_url` for a team member and `images` for a guideline section. They are fetched after the text is saved and listed under `pictures` in the answer.

## What it cannot do yet

- Change the slug. The slug, passwords and domains cannot be changed with `PATCH`.
- Set a password on a brand that already exists. Making a brand public removes its password and needs `confirm_public: true`. `access` accepts only `public` or `restricted`.
- Upload a custom font file. A custom font is a file uploaded in the app; the API does not set one. Fonts you choose come from Google or Adobe (`fonts`).
- Receive a webhook when a brand is created, archived or restored, or when its domain changes.

## MCP tools

The [MCP server](/docs/mcp) has tools for most of this work: `tarkle_list_brands`, `tarkle_get_brand`, `tarkle_create_brand`, `tarkle_update_brand`, `tarkle_lookup_brand_domain`, `tarkle_import_brand_file`, `tarkle_connect_brand_domain` and `tarkle_check_brand_domain`. Archive, restore, the archived brands list, file removal and domain removal are API only. Setting a password when a brand is created is API only too. The [MCP tools](/docs/mcp/tools) page describes each tool.

## Machine-readable description

`GET https://tarkle.com/api/v1/openapi.json` is an OpenAPI file that lists every endpoint, the brand calls included.

## 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