Brand API overviewBeta
What the Brand API reads and changes, which brands a token reaches, and what it cannot do yet.
The Brand API lets your own code work with the Brand Pages in your workspace. It is a JSON API on tarkle.com. This page lists what it can read and change, which brands a token reaches, and what it cannot do yet.
What it is
The API reads and changes the Brand Pages of one workspace, one request at a time. Each request carries an API token, and the scopes of that token decide which calls it can make.
What you can do
With a token that has the matching scope, the API can:
List your brands. The list shows each brand's name, summary, access setting and links, newest first, 25 at a time. Use
limitandcursorto read the next page.Read one brand. The response holds the brand's text, facts, social links, colors, fonts, access setting, tracking IDs, SEO fields, team and press.
Get its files. Logos, the icon, the banner and collection files come with download links. The links expire, and the response says so, so ask again when you need a fresh link.
Get brand.md. The API returns the brand's
brand.md, built by the same code as thebrand.mdin the brand kit download. The API version also lists the Brand Page address in it. The kit download adds the colors and the mark usage terms as separate files, which the API does not return.Read page views, downloads and requests. Choose 30 days (the default), 90 days or all time.
Update a brand. Change its text, links, primary color, access, download approval, draft state and tracking IDs. The Update a brand through the API article lists each field and its limits.
Handle access requests. List the people who asked to download or view a brand, then approve or reject each request. The Manage access requests through the API article covers it.
Which brands a token reaches
A token belongs to one workspace. It reaches every brand in that workspace, whatever the brand's access setting, draft state or download approval. A brand of another workspace answers with "Brand not found", the same as a brand that does not exist.
Each token has scopes, and each call needs the scope listed for it:
Scope | Allows |
|---|---|
| Read brands, their assets, brand.md and analytics |
| Update a brand's text, links, access and settings |
| List download and view requests and approve or reject them |
A token with no scope cannot call the API, and each call answers with a 403 error. When you create a token on the API Tokens tab of the Developers page, tick the scopes under Public API access. The API tokens and webhooks article covers that page. Only the account that owns the workspace can create a token. Tarkle shows the full token once, so copy it when it is created. A revoked token is refused.
The API is for server-side use: it has no CORS support, so do not put a token in browser code. A token in a browser is a leaked token.
What it cannot do yet
Create or delete brands.
Upload logos, banners or collection files.
Set or change a brand's password or domains. The access setting accepts only
publicorrestricted, and setting it topublicremoves the password.Change a brand's slug, secondary color, additional colors, fonts, team members or press.
Send webhooks for brand events.
The machine-readable description
The API publishes an OpenAPI 3.1 description of its calls. Reading it needs no token, and each call in it names the scope it requires.
Versions
Breaking changes ship as a new version of the API, and new fields can appear in the current version. Read the fields you use and ignore the ones you do not know.