---
title: "Quickstart"
description: "Make your first Tarkle API calls in five minutes. Create a token, find your workspace, upload a file and download it again."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

1. **Step 1**

   ## 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.

   ```bash
   export TARKLE_TOKEN=tk_your_token
   ```
2. **Step 2**

   ## 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:

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

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

   ```bash
   export KEY=abcd1234
   ```
3. **Step 3**

   ## List the library

   ```bash
   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](/docs/api/files).
4. **Step 4**

   ## Upload a file

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

   ```bash
   # 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](/docs/api/uploads).
5. **Step 5**

   ## Download it

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

   ```bash
   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](/docs/get-started/authentication): scopes, workspace keys and what a token can reach.
- [Brand API quick start](/docs/api/brands/quick-start): read and update brand pages.
- [Errors](/docs/api/errors): what to do when a call fails.
- [MCP server](/docs/mcp): let an AI assistant do this for you.

Source: https://tarkle.com/docs/get-started/quickstart/index.mdx