Quickstart

This page takes you from nothing to a file uploaded and downloaded through the API. You need a Tarkle account and a terminal with curl.

Create a token
In Tarkle, open Settings > API and create a token. Name it, then tick the scopes it needs. For this page tick files:read and files:write. Copy the token (it starts with tk_). Tarkle shows it once and keeps only a hash.
```
export TARKLE_TOKEN=tk_your_token
```

Find your workspace key

A token belongs to a person and works in every workspace that person can use. Each call names one workspace by its 8-character key. List yours:

curl -H "Authorization: Bearer $TARKLE_TOKEN" https://tarkle.com/api/v1/workspaces

{
  "workspaces": [
    { "workspace_key": "abcd1234", "name": "Studio", "url": "https://studio.tarkle.com", "relationship": "owner" }
  ]
}

export KEY=abcd1234

List the library

curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  https://tarkle.com/api/v1/files

The answer holds entries (folders first, then files) and next_cursor. See Files.

Upload a file

An upload has three parts: start it, send the bytes to the signed URL, then complete it.

# 1. Start. The answer has a signed URL in uploads[0].url and an upload id.
curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "hello.txt", "size": 12, "content_type": "text/plain"}' \
  https://tarkle.com/api/v1/uploads

# 2. Send the bytes to the signed URL from step 1.
curl -X PUT --data-binary "hello world
" "$UPLOAD_URL"

# 3. Complete it. The answer is the new file.
curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  https://tarkle.com/api/v1/uploads/$UPLOAD_ID/complete

Large files go in parts. See Uploads.

Download it

Ask for a short-lived link, then fetch the bytes from storage:

curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  https://tarkle.com/api/v1/files/$FILE_ID/download

The answer has download_url and expires_in (900 seconds).

What next

Authentication: scopes, workspace keys and what a token can reach.
Brand API quick start: read and update brand pages.
Errors: what to do when a call fails.
MCP server: let an AI assistant do this for you.