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:

In Name, enter a name, for example Production.
In Access, keep All workspaces, or choose Only selected workspaces and tick the workspaces the key may reach.
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.

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.

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:

export KEY=abcd1234

3. List your brands

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.

4. Update a brand

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 for every field and its limits.

5. Approve a download request

Find the pending requests:

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:

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.

If a call fails

Errors are problem documents, 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.