---
title: "Upload and manage files with the Tarkle API"
description: "Create an API key in Settings, then list, create, upload, rename, delete and restore files with the Tarkle API, with plan limits and error codes."
canonical: "https://tarkle.com/help/apps-and-developers/how-to-upload-and-manage-files-with-the-tarkle-api-2"
last-updated: 2026-11-04
---

# How to upload and manage files with the Tarkle API

Create an API key, then list, create, upload, rename, delete and restore a workspace's files with the Tarkle API.

The Tarkle API lets your own code list, create, upload, rename, delete and restore the files of a workspace. This article follows those tasks in the order you use them. The reference for every call is in the [developer docs](https://tarkle.com/docs).

## Create an API key

Only the owners and admins of an organization can open the API page and make keys. A member who needs a key asks an owner or admin.

1. Open [API](/dashboard/settings/api) in **Settings**.
2. Click **Create**.
3. Type a **Name** for the key.
4. Under **Access**, choose **All workspaces**, or choose **Only selected workspaces** and tick the workspaces the key may reach.
5. Click **Create**, then click the key in the box to copy it.

The key is shown in full when it is made, so copy it then. An owner or admin can copy it again later from the key's menu with **Copy token**. **Rename** and **Delete** are in the same menu. Deleting a key stops it at once.

A key can read and change everything in Tarkle in the workspaces it reaches, and it acts as the person who made it. It cannot make purchases. Keys made before API keys had full access show a **Legacy** badge and keep their old, limited permissions. They cannot be copied, so create a new key for full access.

Send the key with each call in the Authorization header:

``` Authorization: Bearer <your-tarkle-key> ```

## Name the workspace on each call

Every call that reads or changes files names its workspace in the `X-Workspace-Key` header, using the workspace's eight-character key. An id is refused. The workspaces call returns the key of each workspace your key can reach. A key never does more in a workspace than the person who made it can do there.

## List files and folders

A list shows the files and folders directly inside one folder. Name the folder with its folder id, or with its path such as `/photos/2026`. Leave both out to list the top level, and never send both. Each page holds up to 1,000 entries, and 100 by default. The answer ends with a cursor for the next page. If two folders on the path have the same name, the call answers `ambiguous_path`, so use the folder id instead.

## Create a folder

Send a `name`. To create the folder inside another folder, add that folder's id as `parent_id`. Without it, the folder goes to the top level. A name already used in that folder is refused with `name_taken`.

## Upload a file

An upload has three steps.

1. **Start the upload.** Send the file's `name` and `size` in bytes. Add `folder_id` to put the file in a folder. Without it, the file goes to the top level. The answer holds an upload id and the addresses for the bytes. The first 20 addresses come with it.
2. **Send the bytes.** A file up to 100 MB goes in one request, to the address in the answer. A bigger file is cut into parts, and each part has its own address. Ask for more addresses with `from_part` and `count`, up to 100 at a time. Each address works for one hour.
3. **Finish the upload.** Call the finish step with the upload id. Tarkle puts the file in the folder you chose at the start and returns it. If some bytes have not arrived, the answer is `incomplete` and lists the `missing_parts`. Send those parts, then finish again. An upload not finished within 24 hours expires. To stop an upload early, send a DELETE to its upload id.

Free accepts files up to 1 GB each, and Pro and Agency accept files up to 200 GB each. A file above the plan limit is refused at the start with `file_too_large`. A file that does not fit in the workspace's storage is refused with `storage_full`. For each plan's details, see [Plans and pricing](/pricing).

A file with the same name as one already in the folder is handled the way the app handles it. On Free, the new file is kept as a separate file, renamed so the old one stays. On Pro and Agency, the new upload becomes a new version of the existing file, and you can go back to an earlier version from its [version history](/help/storage/upload-new-file-version-restore-earlier). Two cases can stop and ask first: a file that a transfer uses, and a large file with the same name and size. The answer is `conflict`. Send `on_conflict` with `version`, `separate` or `skip` to decide.

## Rename, move and delete

To rename a file or folder, send a new `name`. To move it, send the id of the destination folder as `parent_id`, or `null` for the top level. You can send both at once. A folder cannot be moved into itself or into one of its own subfolders. Some items are protected, such as system and team folders, and they answer `protected`.

Deleting moves a file or folder to the bin. If an active transfer uses it, the answer is `transfer_active` and lists those transfers. To delete those transfers too, send the delete again with `confirm_delete_transfers=true`. The [File and folder management](/help/storage/file-and-folder-management-in-tarkle) article explains the bin in the app.

## Restore from the bin

Send a POST to the id of the file or folder to bring it back. Only items in the bin can be restored. Any other item answers `not_deleted`. Deleted items wait in the bin for 30 days on Free and 90 days on Pro. After that they answer `expired`. If the folder the item was in is still in the bin, restore that folder first, or the answer is `parent_unavailable`.

## When a call fails

A failed call returns an HTTP status and a body with a `code` and a `detail` message. Branch on the `code`, not on the message. These are the codes you will meet most often:

- `name_taken` (409): a file or folder with that name is already in the folder.
- `conflict` (409): a same-name upload needs an `on_conflict` choice.
- `incomplete` (409): some parts of the upload are still to be sent.
- `transfer_active` (409): an active transfer uses the item.
- `protected` (403): the item cannot be changed through the API.
- `forbidden` (403): the person who made the key may not do this in that workspace.
- `no_access` (403): the key does not reach that workspace.
- `unauthorized` (401): the key is missing, wrong or deleted.
- `file_too_large` and `storage_full` (413): the plan limits above.
- `rate_limited` (429): too many calls in one minute. File calls allow 600 a minute for each key. Wait the number of seconds in the `Retry-After` header, then try again.

The [developer docs](https://tarkle.com/docs) list every error code.

## What happens next

A finished upload shows in the folder you chose, and in [Files](/dashboard/files) of the workspace.

## Related articles

- [Cloud storage for business files with Tarkle](/help/storage/cloud-storage-for-business-files-with-tarkle)
- [Developer API](/features/developer-api)

Source: https://tarkle.com/help/apps-and-developers/how-to-upload-and-manage-files-with-the-tarkle-api-2