Brand API

The Brand API reads and changes the Brand Pages of a workspace, one request at a time. It is part of the Tarkle API at https://tarkle.com/api/v1. Start with the API overview for the shared rules, and read Authentication to see how your API key is sent.

What you can do

List brands. Name, summary, access, links and draft state, newest first. The default page holds 25 brands, and limit can ask for up to 100.
Read one brand. Text, facts, social links, colors, fonts, access, tracking IDs, SEO fields, team, press and guidelines.
Get its files and brand.md. GET /brands/{brand}/assets lists the icon, logos, banner and collection files, each with a short-lived download link. GET /brands/{brand}/markdown returns the brand as brand.md.
Read page views, downloads and requests. period is 30d (default), 90d or all.
Update a brand. Text, links, colors, fonts, team, press, guidelines and access. See Update a brand.
Create, archive and restore brands. A new brand is a private draft. Deleting a brand archives it, and an archived brand can be restored. See Create, delete and restore brands.
Upload, import and remove files. Icon, logos, banner, social image, favicon and collection files, plus team photos and guideline images. See Upload brand files.
Connect a domain. Connect, check and remove a brand’s own domain. See Brand domains.
Look up a brand from a website. POST /brand-lookup returns suggested details and pictures for a website address and saves nothing.
Get events. Signed webhooks for brand views, downloads, updates and access requests. Views are sent only to endpoints that ask for them.
Handle access requests. List the people who asked to download or view a brand, then approve or reject each one. See Access requests.

Keys and workspaces

Send your API key on every call as Authorization: Bearer <your-tarkle-key>. Owners and admins of an organization create keys in Settings, API. A key can do everything the API can, in the workspaces it reaches, and it acts as the person who made it. The one thing a key cannot do is make a purchase.

A key limited to chosen workspaces answers 403 no_access for any other workspace. Name the workspace on every call with the X-Workspace-Key header, which takes the 8-character workspace key, not its id. An id is refused with 400 workspace_key_required. Only GET /workspaces works without it.

Brand endpoints also need the key’s creator to be an owner or admin of that workspace. A brand of another workspace answers 404 not_found, the same as a brand that does not exist.

Each endpoint checks one internal scope: brands:read to read, brands:create to create, archive and restore, or brands:files to upload and remove files. A key holds all of them, so you never choose them. A key that lacks the scope a call needs answers 403 forbidden.

curl -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $WORKSPACE_KEY" https://tarkle.com/api/v1/brands

Keep the key on your server. Never put it in browser code or a public repository.

Create a brand

POST /brands adds a brand as a private draft. name is required, and so are summary and industry. At the plan’s brand page limit the call answers 403 forbidden, and a slug already used in the workspace answers 409 name_taken.

Send password to protect the brand from the start. It must be at least 8 characters. Setting a password on create is API only: the MCP server cannot set one.

Archive and restore

DELETE /brands/{brand} archives a brand instead of deleting it for good. The page goes offline and answers 404, the app stops listing it, its address (slug) and its place under the plan’s brand page limit are freed, and its domains are detached. The brand, its files and its settings are kept with no time limit. Access requests, analytics and the kit link are not kept. The call needs confirm_delete: true, in the query or the body, otherwise it answers 400 confirmation_required.

GET /archived-brands lists the archived brands of the workspace, newest first. POST /archived-brands/{brand}/restore puts one back with the same id and content, using the id from that list. It counts toward the plan’s brand page limit, so it answers 403 forbidden at the limit. If the address is taken now, send another slug in the body, otherwise the call answers 409 name_taken. Domains are not restored; connect them again with Brand domains.

Files and pictures

Upload a brand file in two steps. POST /brands/{brand}/files returns a signed upload address, and you complete the upload with the file id. POST /brands/{brand}/files/import does both steps in one call for a public https image address. Remove a file with DELETE /brands/{brand}/files?slot=.... See Upload brand files.

Team photos and guideline images can be given as public https addresses too, as photo_url for a team member and images for a guideline section. They are fetched after the text is saved and listed under pictures in the answer.

What it cannot do yet

Change the slug. The slug, passwords and domains cannot be changed with PATCH.
Set a password on a brand that already exists. Making a brand public removes its password and needs confirm_public: true. access accepts only public or restricted.
Upload a custom font file. A custom font is a file uploaded in the app; the API does not set one. Fonts you choose come from Google or Adobe (fonts).
Receive a webhook when a brand is created, archived or restored, or when its domain changes.

MCP tools

The MCP server has tools for most of this work: tarkle_list_brands, tarkle_get_brand, tarkle_create_brand, tarkle_update_brand, tarkle_lookup_brand_domain, tarkle_import_brand_file, tarkle_connect_brand_domain and tarkle_check_brand_domain. Archive, restore, the archived brands list, file removal and domain removal are API only. Setting a password when a brand is created is API only too. The MCP tools page describes each tool.

Machine-readable description

GET https://tarkle.com/api/v1/openapi.json is an OpenAPI file that lists every endpoint, the brand calls included.