---
title: "Create, delete and restore brands"
description: "Add a brand, move it to the bin, list the bin and restore a brand, with the plan rules that apply."
---

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

# Create, delete and restore brands

These calls need the `brands:create` scope, and the token's creator must be an owner or admin of the workspace named in `X-Workspace-Key`.

## Create a brand

`POST /brands` adds a brand. Only `name` is required.

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

The call answers `201` with the whole brand, as `GET /brands/{brand}` shows it.

- **Fields.** The same fields as [Update a brand](/docs/api/brands/update-a-brand), plus `slug`. The slug defaults to the name (lowercase letters, numbers and single hyphens, 48 characters at most).
- **Limits.** Create uses the limits of the app: `name` 48 characters, `summary` 200, `story` 2,000. A longer value is refused with `400 invalid_request`, not cut.
- **Not accepted on create.** `access`, `is_draft` and `confirm_public`. A new brand is always a private draft. Open it later with `PATCH /brands/{brand}`, which keeps its own `confirm_public` rule.
- **The plan's brand page limit** applies as in the app. At the limit the call answers `403 forbidden` and `details.entitlement` names the limit. Free workspaces have one brand page, and deleted brands do not count.
- **A slug already used in the workspace** answers `409 name_taken`.

## Delete a brand

`DELETE /brands/{brand}` moves the brand to the bin. It needs `confirm_delete: true`, in the JSON body or as `?confirm_delete=true`. Without it the call answers `400 confirmation_required` and changes nothing.

```bash
curl -X DELETE -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"confirm_delete": true}' \
  https://tarkle.com/api/v1/brands/acme-bank
```

The answer holds `deleted: true`, the brand's `id`, `slug`, `name`, `deleted_at` and `restorable_until`.

- **How long it can come back** follows the plan's recovery bin, the same as files: 30 days on Free, 90 days on Pro and Agency. If Tarkle cannot confirm the plan, nothing is deleted and the call answers `503 entitlement_unresolved`.
- **What goes offline.** The page, its slug and its place under the plan's brand page limit are freed straight away.
- **Domains** are detached from hosting and are **not** restored. Connect a domain again after a restore.
- **Not kept:** access requests, analytics and the kit link.
- **Stored files** stay until the bin removes the brand for good.

## List deleted brands

`GET /deleted-brands` lists the brands that can still be restored, newest deletion first. Each item has `id`, `slug`, `name`, `deleted_at`, `restorable_until` and `domains` (the domains that were detached). Brands past their retention are not listed.

## Restore a brand

`POST /deleted-brands/{brand}/restore` puts a deleted brand back with the same id and content. `{brand}` is the id from the list.

```bash
curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"slug": "acme-bank-2"}' \
  https://tarkle.com/api/v1/deleted-brands/$BRAND_ID/restore
```

The body is optional. Send `slug` to restore under another address.

| Answer | Meaning |
| --- | --- |
| `200` | The brand is back. The body is the whole brand. |
| `403 forbidden` | The workspace is at its brand page limit. |
| `404 not_found` | No deleted brand with that id in this workspace. |
| `409 name_taken` | The slug is used again. Send another `slug`. |
| `410 expired` | The brand was deleted longer ago than the plan keeps it. |

Every call here is recorded in the workspace Activity (`brand.created`, `brand.deleted`, `brand.restored`) with the token's name. They accept an [`Idempotency-Key`](/docs/api/idempotency).

Source: https://tarkle.com/docs/api/brands/create-and-delete/index.mdx