Add, import and delete brand files

A brand’s pictures and files reach a brand in one of two ways. You can upload the file in three steps, or give Tarkle the address of a public image and let it fetch the image in one call. You can also delete a file from a brand. Every call here sends your API key as Authorization: Bearer <your-tarkle-key>, and it names the workspace with its key in the X-Workspace-Key header. The person who made the key must be an owner or admin of that workspace. Every API key holds the brands:files scope. Keys have no scope picker: the only choice when a key is made is which workspaces it reaches. For the headers, see Authentication.

Choose the place

Every call names a slot, the place the file is for.

Any other slot answers 400 invalid_request.

1. Start the upload

POST /brands/{brand}/files with the place the file is for.

curl -X POST -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot": "icon", "size": 18204, "filename": "icon.png"}' \
  https://tarkle.com/api/v1/brands/acme-bank/files

size and filename are optional. They let a file that is too large, or of a type the place does not take, be refused before you upload it. The answer holds:

• file_id, which you use in step 3. It only works for this brand and this place.
• upload.method (PUT) and upload.url. The address expires after upload.expires_in seconds (3,600).
• max_bytes and extensions: the largest size and the allowed file types for that place, or null for any type.

2. Send the file

PUT the file bytes to upload.url. Send the bytes as the body, with no Authorization header.

curl -X PUT --data-binary @icon.png "$UPLOAD_URL"

3. Complete the upload

POST /brands/{brand}/files/{file_id}/complete. Tarkle checks what was stored and attaches it to the brand.

curl -X POST -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $KEY" \
  https://tarkle.com/api/v1/brands/acme-bank/files/$FILE_ID/complete

The checks are the ones of the brand editor: the file’s real type (from its first bytes, not its name), its size, and that it arrived. The limits by place are:

The five places on the brand row (icon, main_logo, banner, social_image, favicon) take no body. The others take these fields:

• logo: name, type (primary, secondary, monochrome, reversed, icon, favicon, square or social media) and usage (digital, print or all purpose).
• asset: collection_id, or collection_name to start a new collection, plus optional name and type.
• team_photo: member_id, or member_name when the member has no id.
• guideline_image: section_id (required), kind (image, do or dont, and image when left out) and caption.

The answer (200) holds slot, file_id, size and already_attached. It also holds the id of what was attached: logo_id for a logo, collection_id and asset_file_id for a collection file, member_id for a team photo, and section_id and image_id for a guideline image.

Completing the same file again answers the same with already_attached: true and changes nothing. A replaced icon, main logo, banner, social image, favicon or team photo is removed from storage unless the brand still uses it. A file that fails the checks is removed too.

Import a picture by address

POST /brands/{brand}/files/import fetches a public image and attaches it in one call. Send slot and url, plus the fields the complete step takes for that place, such as type and usage for a logo or member_id for a team photo.

curl -X POST -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot": "favicon", "url": "https://example.com/favicon.png"}' \
  https://tarkle.com/api/v1/brands/acme-bank/files/import

The url must be an https address without a username or password, and it must point to a public image no larger than the place allows. The same checks as an upload run on the image. When the address cannot be read or the image is refused, nothing is attached and nothing is kept in storage. The answer is 201 and has the same fields as completing an upload.

Delete a file

DELETE /brands/{brand}/files?slot=... takes one file off the brand. The query names the file:

curl -X DELETE -H "Authorization: Bearer $TARKLE_KEY" -H "X-Workspace-Key: $KEY" \
  "https://tarkle.com/api/v1/brands/acme-bank/files?slot=favicon"

The answer is 200 with removed, which holds the slot and the removed_id. The removed_id is the id of the logo, collection file, team member or image, and null for the five places on the brand row. The stored file is deleted too unless something of the brand still uses it. A file that is not there answers 404 not_found.

The MCP server cannot delete a brand file. It adds brand images by address with tarkle_import_brand_file, and no tool it offers removes a brand file, so use this endpoint to delete one.

Deleting a whole brand is a different call, DELETE /brands/{brand}. It archives the brand; see Create, delete and restore brands.

Team photos and guideline images in a brand request

POST /brands and PATCH /brands/{brand} also take pictures by address: a team member’s photo_url and a guideline section’s images, each with a url, a kind and a caption. Tarkle fetches them after the text is saved, with the same checks as an upload. A request holds up to 12 pictures. A picture that fails is listed in pictures. See Update a brand.

Activity and webhooks

An upload that attaches a file, an import and a delete are recorded in the workspace Activity as brand.updated. Each one fires a brand.updated webhook event. Completing a file that is already attached fires nothing.

Errors

Match on code to tell errors apart. The answers that apply to this page are:

The full list of codes is in Errors.