Brand API quick startBeta
Create a Brand API token, then list your brands, update one and approve a download request.
This page walks through the first calls to the Brand API: list your brands, update one, and approve a download request. Start by creating a token with the scopes these calls need.
1. Create a token
Open Developers in your workspace and click the API Tokens tab.
Click New token.
In Token name, enter a name for the token, for example Production API.
Under Public API access, tick each scope the token needs. The table below lists them.
Click Create.
In the Token created window, click the token to copy it, then click Done.
Scope | Allows |
|---|---|
| Read brands, their assets, |
| Update a brand's text, links, access and settings. |
| List download and view requests and approve or reject them. |
A token with no scope ticked cannot call the Brand API, and the API answers with a 403 error. Only the owner of the workspace can create tokens. The token starts with tk_, and Tarkle shows it only once, so copy it before you close the window. Tarkle keeps only a hash of it, so the token cannot be shown again: if you lose it, create a new one. The Developers page is described in API tokens and webhooks.
2. List your brands
Send the token in an Authorization header as a bearer token, with the value Bearer followed by your token. Then send a GET request to the brands list. The list shows the brands of your workspace, newest first, 25 at a time. Each brand has an id and a slug, and either one identifies the brand in the calls below.
Add limit (from 1 to 100) to change the page size. Pass the next_cursor value of a response as cursor to get the next page. It is null on the last page. The Brand API endpoints article lists the address and scope of every call.
3. Update a brand
Send a PATCH request for one brand. Put the brand's id or slug in the address, and send a JSON object that holds at least one field, for example:
`` {"primary_color": "#714CB6"} ``
The response is the full brand with the new values. The fields include name, summary, primary_color (a hex color such as #714CB6), access (public or restricted) and download_approval. Setting access to restricted first needs a contact or an organization on the brand, or the call returns an error. A body with no valid field returns the error "Nothing to update". The update a brand through the API article lists the fields a PATCH request can change, with their limits.
4. Approve a download request
Find the request first. Send a GET request for the brand's requests with status set to pending. The other values are approved and rejected. Each request has an id.
To approve a request, send a POST request for that request with this JSON body:
`` {"action": "approve"} ``
Approving a download request emails the visitor a link to download the brand. Approving a view request only marks it as approved, with no email. To reject a request, send the same body with "reject" in place of "approve". Rejecting takes back the visitor's link. If the request already has that decision, the call returns a 409 error. The manage access requests through the API article covers listing and deciding requests.
What happens next
A successful call returns JSON. An error returns an error object with a code and a message, and each token can make 120 requests per minute. The errors, paging and rate limits article explains both.