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.
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.
Open API in Settings.
Click Create.
Type a Name for the key.
Under Access, choose All workspaces, or choose Only selected workspaces and tick the workspaces the key may reach.
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.
Start the upload. Send the file's
nameandsizein bytes. Addfolder_idto 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.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_partandcount, up to 100 at a time. Each address works for one hour.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
incompleteand lists themissing_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.
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. 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 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 anon_conflictchoice.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_largeandstorage_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 theRetry-Afterheader, then try again.
The developer docs list every error code.
What happens next
A finished upload shows in the folder you chose, and in Files of the workspace.