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

In Tarkle, open Settings > API.
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.
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.

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:

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

export KEY=abcd1234

3. List your brands

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

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

5. Approve a download request

Find pending requests, then decide one:

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.

If a call fails

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