Brand API endpointsBeta
Every Brand API call with its scope, the parameters it accepts and the fields it returns.
The paths on this page are relative to the Tarkle API version 1 base address. This page lists each call with the scope its token needs, the parameters it accepts and what it returns. To create a token and make a first call, follow the Brand API quick start.
Send your API token in the Authorization header as Bearer tk_.... A token must have the scope a call needs, otherwise the request returns 403. A missing or revoked token returns 401. New fields can be added to version 1 of the API. A change that would break existing requests goes to a new version, not to v1. Every response carries the header X-Tarkle-Api-Version: v1.
{brand} is the brand's id (a uuid) or its slug. A brand that belongs to another workspace returns 404, the same as a brand that does not exist. A value that is neither an id nor a slug returns 400. Errors always have the same shape. The paging and rate limit rules are in Brand API errors, paging and rate limits.
Calls
Call | Scope | What it does |
|---|---|---|
|
| Your workspace's brands, newest first. Accepts |
|
| One brand in full. |
|
| Change a brand. See Update a brand through the API. |
|
| Logos, icon, banner and collection files, each with a |
|
| The brand's |
|
| Views, downloads and requests. |
|
| People who asked for access to the brand. Filter with |
|
| Approve or reject a request. See Manage access requests through the API. |
The list response
GET /brands returns data, an array, and next_cursor. Each item has id, slug, name, summary, access, is_draft, download_approval, indexable, created_at and urls (the public page address and the api address of that brand).
Fields of a brand
GET /brands/{brand} returns these fields. Text fields such as summary and story come back as an empty string when they are not set, not as null.
Field | Contents |
|---|---|
| The brand's identifiers and name. |
| Short description and longer story, as text. |
| Company facts, as text. |
| The brand's website address. |
|
|
|
|
|
|
|
|
| Whether the brand is a draft, and whether downloads need your approval. |
| True when the page is public and not a draft, so search engines may list it. |
|
|
| An object with |
| A |
| Links with |
|
|
| When the brand was created. |
Files
GET /brands/{brand}/assets returns brand with its id and slug, then images, logos and collections.
imageslists only the icon, main logo and banner that are set. Each one has aroleoficon,main_logoorbanner.logoslists the other logos, each withid,name,typeanddownload_url. Logos used as the main logo or the icon are left out.collectionslists each asset collection withid,name,descriptionandfiles. Each file hasid,name,type,size(nullwhen not set) anddownload_url.
Every file has a download_url. These links expire, so fetch a file soon after you list it. The response includes links_expire: true as a reminder.
Access requests
GET /brands/{brand}/requests returns data and next_cursor, newest first. Each item has id, kind, name, company, email, message, status, created_at and decided_at. A page holds 25 items unless you send limit, and you move to the next page with cursor. An unknown status value returns 400.
POST /brands/{brand}/requests/{request} takes a JSON body with action set to approve or reject. The request must be a UUID, otherwise the call returns 400. A request that does not belong to this brand returns 404. The response gives the request's id and its new status (approved or rejected). It also includes an emailed value when the decision returns one.
Analytics
GET /brands/{brand}/analytics returns period, then views, downloads and requests. Each has a total and a series. Any period value other than 30d, 90d or all is read as 30d, with no error. 30d and 90d return one point per day, and all returns one point per month.
The total counts every row in the period. The series is built from the 2,000 most recent rows for each number, so a brand with more rows than that can have a series that adds up to less than its total.
The numbers cover only the brand in the path. The Brands page of a workspace shows the same overview for all of that workspace's brands together, so its totals can be higher when the workspace has more than one brand. Both use the same periods. To see what the cards in the dashboard show, read How do I see views, downloads and requests for my brand pages?.