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

> 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. You need an API key first, and only the owner and the admins of an organization can make one.

## 1. Create an API key

Open **Settings > API** and stay on the **API keys** tab. Only the owner and the admins of your organization can see this page. Click **Create** and fill in the dialog:

1. In **Name**, enter a name, for example `Production`.
2. In **Access**, keep **All workspaces**, or choose **Only selected workspaces** and tick the workspaces the key may reach.
3. Click **Create**. The dialog shows the key, which starts with `tk_`. Click the key to copy it.

A key has no list of scopes to choose. It can read and change everything in Tarkle for the workspaces it reaches, and it acts as the person who made it. It cannot make purchases. Treat the key like a password, and keep it in an environment variable on a server.

```bash
export TARKLE_API_KEY=<your-tarkle-key>
```

The key stays in the list. An owner or admin can copy it again from the key's menu with **Copy token**, and can rename it or delete it from the same menu. A key with a **Legacy** badge was made before keys had full access. It keeps its old, limited permissions, so a call outside them returns `403`, and it has no **Copy token**. Create a new key to get full access.

## 2. Find the workspace key

Every call that works inside a workspace names it with the 8-character `workspace_key`, sent in the `X-Workspace-Key` header. A call without it is refused, and so is a workspace id sent in its place. `GET /workspaces` lists the workspaces the key can reach, each with its `workspace_key`. A key limited to some workspaces lists only those. For how the key is sent on every call, see [Authentication](/docs/get-started/authentication).

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

Copy the `workspace_key` of the workspace you want into a variable:

```bash
export KEY=abcd1234
```

## 3. List your brands

```bash
curl -H "Authorization: Bearer $TARKLE_API_KEY" -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. `limit` takes 1 to 100. Pass `next_cursor` back as `cursor` to read the next page; it is `null` on the last page. See [Paging and limits](/docs/api/paging-and-limits).

## 4. Update a brand

```bash
curl -X PATCH -H "Authorization: Bearer $TARKLE_API_KEY" -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 the pending requests:

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

Then approve one, or send `"action": "reject"` to reject it:

```bash
curl -X POST -H "Authorization: Bearer $TARKLE_API_KEY" -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 link that gives their browser access to the downloads. Rejecting takes that access back. See [Access requests](/docs/api/brands/access-requests).

## If a call fails

Errors are [problem documents](/docs/api/errors), so branch on the `code` member.

- `401` with `unauthorized`: the key is missing, malformed, invalid or deleted. Send `Authorization: Bearer <your-tarkle-key>`.
- `403` with `no_access`: the workspace key is unknown, the key is limited to other workspaces, or the person who made the key cannot reach that workspace.
- `403` with `forbidden`: the key was made before keys had full access and lacks the scope the call needs, or a brand call came from a key whose creator is not an owner or admin of that workspace.
- `400` with `workspace_key_required`: a workspace id was sent where the 8-character workspace key belongs.
- `429` with `rate_limited`: wait the number of seconds in `Retry-After`.

To stop a key, delete it from its menu in **Settings > API**. It stops working right away, everywhere it is used.

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