---
title: "Quickstart"
description: "Make your first Tarkle API calls in five minutes. Create an API key, 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 an account in an organization where you are an owner or admin, and a terminal with `curl`.

One API key does everything the API and the MCP server can do, in the workspaces it reaches. It acts as the person who created it, with that person's role in each workspace. The one thing it cannot do is make purchases.

1. **Step 1**

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

   ```bash
   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.
2. **Step 2**

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

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

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

   ```bash
   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`.
3. **Step 3**

   ## List the library

   ```bash
   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](/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. Start it with the file name, the size and the content type:

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

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

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

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

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

   ```json
   { "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:

   ```bash
   curl -o hello.txt "$DOWNLOAD_URL"
   ```

## What next

- [Authentication](/docs/get-started/authentication): how the key is sent and which workspaces it reaches.
- [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): connect an AI assistant to Tarkle.

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