---
title: "Brand API quick start"
description: "Create a token, find your workspace key, list brands, update one and approve a download request."
---

> 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 quick start

This page walks through the first calls: list your brands, update one and approve a download request.

## 1. Create a token

1. In Tarkle, open **Settings > API**.
2. Create a token, name it (for example `Production`) and tick the scopes it needs: `brands:read`, `brands:write` and `brands:requests` cover everything on this page. Add `brands:create`, `brands:files`, `brands:domains` and `webhooks:manage` only for the calls that need them.
3. Copy the token (it starts with `tk_`). Tarkle shows it once and keeps only a hash, so create a new one if you lose it.

Keep the token in an environment variable on a server.

```bash
export TARKLE_TOKEN=tk_your_token
```

## 2. Find the workspace key

A token can work in every workspace its creator can use, so each call names one. `GET /workspaces` lists them with the 8-character `workspace_key`:

```bash
curl -H "Authorization: Bearer $TARKLE_TOKEN" https://tarkle.com/api/v1/workspaces
```

```bash
export KEY=abcd1234
```

## 3. List your brands

```bash
curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  "https://tarkle.com/api/v1/brands?limit=10"
```

Each brand has an `id` and a `slug`. Either one identifies the brand in the calls below. Pass `next_cursor` back as `cursor` to read the next page; it is `null` on the last page.

## 4. Update a brand

```bash
curl -X PATCH -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Business banking for small firms"}' \
  https://tarkle.com/api/v1/brands/acme
```

The answer is the whole brand with the new values. Send only the fields you want to change. See [Update a brand](/docs/api/brands/update-a-brand) for every field and its limits.

## 5. Approve a download request

Find pending requests, then decide one:

```bash
curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  "https://tarkle.com/api/v1/brands/acme/requests?status=pending"

curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"action": "approve"}' \
  https://tarkle.com/api/v1/brands/acme/requests/REQUEST_ID
```

Approving a download request emails the visitor a download link. See [Access requests](/docs/api/brands/access-requests).

## If a call fails

Errors are [problem documents](/docs/api/errors). Branch on the `code` member. A `401` means the token is missing, invalid or retired, a `403` means a missing scope or no access to that workspace, and a `429` means wait `Retry-After` seconds.

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