Quickstart

Create an API key

In Tarkle, open Settings > API. The API keys tab lists every key of your organization, and the Webhooks tab sits next to it. Only an owner or admin sees this page.

Click Create, enter a name in Name, and pick the access under Access. All workspaces lets the key reach every workspace of the organization. Only selected workspaces lets you tick the workspaces it may reach. There are no scopes to tick and no expiry date to set.

Click Create again. Tarkle shows the key once, in the API key created dialog, and it starts with tk_. Click the key to copy it, then export it:

export TARKLE_KEY=<your-tarkle-key>

You can copy the key again later from its row menu: choose Copy token. Rename and Delete are in the same menu, and Delete stops the key at once. A key with the Legacy badge has no Copy token item, and it does not open the MCP server either. Create a new key for full access.

Find your workspace key

Each call names one workspace by its 8-character key, sent in the X-Workspace-Key header. List the workspaces your key can use:

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

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

export KEY=abcd1234

The relationship field says how the key’s creator is connected to each workspace: owner, member or linked. A key limited to selected workspaces lists only those. A call to any other workspace answers 403 with the code no_access.

List the library

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

The answer holds entries, with folders first and then files, and next_cursor for the next page. See Files.

Upload a file

An upload has three parts: start it, send the bytes to the signed URL, then complete it. Start it with the file name, the size and the content type:

# 1. Start. The answer holds the upload id and a list called uploads.
curl -X POST -H "Authorization: Bearer $TARKLE_KEY" -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

Copy the id from the answer into UPLOAD_ID, and the url of the first item in uploads into UPLOAD_URL. Then send the bytes to that URL:

# 2. Send the bytes to the signed URL.
printf 'hello world\n' | curl -X PUT -H "Content-Type: text/plain" --data-binary @- "$UPLOAD_URL"

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

Larger files are sent in several parts; see Uploads.

Download it

Ask for a short-lived link, then fetch the bytes with it. Take the file id from the complete answer as FILE_ID.

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

{ "id": "123", "name": "hello.txt", "size": 12, "download_url": "https://...", "expires_in": 900 }

The answer has download_url and expires_in. The link works without the key for 15 minutes, so fetch it at once or ask again for a fresh one. Copy download_url into DOWNLOAD_URL and save the file:

curl -o hello.txt "$DOWNLOAD_URL"