How to manage brand pages with the Tarkle API
Create, update, publish, archive and restore brand pages, and add their files and domains, with a Tarkle API key.
You can manage brand pages from your own code with a Tarkle API key. This article follows the order of the work: get a key, create a brand page, update it, publish it, archive and restore it, add its files and pictures, and connect a custom domain. The calls, their fields and their answers are in the developer documentation.
Get an API key
Only the owners and admins of your organization can see and make API keys. A member who needs a key asks an owner or admin.
Open API in Settings. API keys belong to the organization, not to one workspace.
Click Create.
Type a Name so you can tell the key apart later.
Under Access, choose All workspaces, or choose Only selected workspaces and tick the workspaces the key may reach.
Click Create in the dialog. Tarkle shows the key once. Click the key to copy it.
A key does everything the API can do in the workspaces it reaches, except purchases. You do not choose permissions for it, and it acts as the person who made it. For brand pages, that person must be an owner or admin of the workspace. A call to a workspace the key does not reach is refused with a 403 error.
To copy a key again, open its Key actions menu and choose Copy token. The same menu has Rename and Delete. Deleting a key stops it at once, everywhere it is used. A key made before this change can show a Legacy badge. It keeps its older, limited access and cannot be copied, so create a new key for full access.
Send the key with each request in the header Authorization: Bearer <your-tarkle-key>, and name the workspace with its workspace key in the X-Workspace-Key header. Brand calls allow 120 requests a minute for each key. A call over that limit is refused until the time in Retry-After has passed.
Create a brand page
Send a name, a summary and an industry. These three are required, and every other field is optional. The industry must be one of the choices the brand editor uses. A new brand page is always a private draft, not public. You can set a password when you create the page, at least 8 characters long.
The other fields are the same as in the app, described in How to create a brand page. Free allows one brand page for the whole organization, and Pro and Agency allow unlimited brand pages. The details are in Brand page plans and limits. A create past the limit is refused with a 403 error.
Update a brand page
An update changes the text, links, colors, fonts, team, press, guidelines, access, download approval and tracking of a brand page.
Access is either public or restricted. Making a brand page public lets anyone open it and removes its password, so the update must also send confirm_public set to true. A restricted brand page needs a contact or an organization assigned to it first. To assign one in the app, follow How do I share a brand page with a client?.
Publish a brand page
A brand page stays a draft until you publish it. To publish, send an update that turns the draft setting off. Publishing does not make the page public. Access is set separately, so set it to public too if anyone should open the page. Who can open a brand page? explains the choices.
Archive and restore a brand page
Through the API, deleting a brand page archives it. The API never removes a brand page for good. The delete call needs confirm_delete set to true, in the request body or in the query string. An archived brand page goes offline and leaves Brands in the app. Its domains are disconnected, while its details, logos, colors, images and files are kept.
Archived brand pages do not expire. The list of them, newest first, is the archived-brands call in the developer documentation. To restore one, call the restore action with its id. The brand page comes back with the same id. If its address is taken now, send a new slug with the restore, or the request fails with a 409 error. Restoring counts against the plan's brand page limit, the same as creating one. Domains are not restored, so connect them again.
Add files and pictures
Brand page files are added in three steps. Each file goes to one slot: icon, main logo, banner, social image, favicon, an extra logo or a collection file.
Start an upload for one slot. Tarkle returns a file id and an upload address, which expires.
Send the file to that address with a PUT request.
Complete the upload with the file id. Tarkle checks the uploaded file and attaches it to the brand page.
If the picture is already on a public https address, one call fetches it and attaches it to a slot. Team photos and guideline images are sent as addresses when you update the brand page. Tarkle fetches each one after the text is saved, and a picture that fails does not undo the saved text.
To remove a file, call the delete for the brand page's files with its slot. An extra logo or a collection file also needs its id. The file is taken off the brand page.
Connect a custom domain
Send the domain name, such as brand.example.com, without https://, a path or a port. Tarkle answers with the DNS records to add at your DNS host. The plan's brand page domain limit applies as it does in the app. To check the setup again, read the domain: Tarkle checks it with its hosting provider again. To disconnect the domain, remove it. The steps in the app are in How do I use my own domain for a brand page?.
What happens next
Brand pages belong to a workspace. After a change, open Brands in that workspace to check the page.