What is the Tarkle API?
The Tarkle API lets your own code read and change files, Brand Pages and storage usage in your workspaces.
The Tarkle API lets your own code read and change what is in your Tarkle workspaces: files, folders, uploads, Brand Pages, custom domains for Brand Pages and storage usage. This article explains what the API covers, what it does not cover yet, and how to make your first call.
Who the API is for
Your own code can use the API to work with your Tarkle files, Brand Pages or storage. Its answers are JSON, so any language that can send a web request can call it. The API reference is in the API documentation, not in the app.
What you can do with the API
Most calls work inside one workspace, and each of them names that workspace by its key, as described under Name the workspace on each call. Inside a workspace, the API covers these areas:
Workspaces. List the workspaces your key can reach, with the workspace key each one needs.
Files and folders. List what is in a folder, find an item by its path, read one file and get a short-lived download link, create a folder, copy a file, rename or move an item, move an item to the bin and restore it.
Uploads. Upload a file into a folder. A small file gets one upload address. A larger file is split into parts, and each part has its own address. Your code sends the bytes to those addresses and then finishes the upload. A file larger than your plan allows is refused.
Usage. Read how much storage the workspace uses and the limit of its plan, in bytes.
Brand Pages. List, read, create, change, archive and restore Brand Pages. Deleting a Brand Page through the API archives it, and an archived Brand Page can be restored later. You can also read a Brand Page's views, downloads and requests, and approve or reject the download and view requests. For how approval works in the app, see How do download approval and access requests work?
Brand Page files. Upload a Brand Page's icon, logos, banner, social image, favicon and collection files, import a picture from a public web address, or remove a file.
Custom domains. Connect a custom domain to a Brand Page, check its setup, or remove it. The API returns the DNS records to add. The same rules as in the app apply, as described in How do I use my own domain for a brand page?
Webhooks. Add an address that receives signed events from Tarkle, send it a test event and read its delivery log.
Brand calls also need the person who made the key to be an owner or admin of that workspace. Webhook calls need the same. A Brand Page can get a password when the API creates it. The update call cannot change a Brand Page's slug, password or domains, and domains have their own calls.
What the API does not cover yet
The API has no endpoints yet for file transfers, transfer pages, file requests, Feedback, contacts, the client portal, the organization, teams, or domains for transfers and events. The developer docs list these areas as not in the API yet. Buying a plan is not possible with an API key either.
How to start
Create an API key
API keys belong to your organization. Only its owners and admins can see the API page and make keys.
Open API in Settings, on the API keys tab.
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. The window titled API key created shows the key. It appears in a box labelled Token.
Click the key to copy it, then click Done.
A key can read and change everything in Tarkle for the workspaces it may reach, and it works for the API and the MCP server. Treat it like a password. A key limited to some workspaces is refused in every other workspace.
Copy, rename or delete a key
Every key of your organization is listed on the same page, with its name, its access and the person who made it. Open the menu at the end of a key's row to:
Copy token to copy the key again. A key made before copying existed cannot be copied, and its item is unavailable.
Rename to change its name.
Delete to stop it. A deleted key stops working at once, everywhere it is used.
A key works until you delete it. A key with a Legacy badge was made before full access existed. It keeps only the access it was given and cannot connect an AI assistant, so create a new key for full access. If you are a member and need a key, ask an owner or admin to make it.
Name the workspace on each call
Each call that reads or changes something inside a workspace names that workspace with its workspace key, in the X-Workspace-Key header. A workspace key is eight lowercase letters and digits. A workspace id is refused. The workspace list call returns the key of each workspace your key can reach.
Send the key
Send your API key in the Authorization header, with the word Bearer before it:
Authorization: Bearer <your-tarkle-key>
The API answers in JSON. When a call fails, the answer carries a code.
Use your key with an AI assistant
ChatGPT, Claude and Grok connect to the MCP server with browser sign-in and need no key. Coding assistants and other clients that can send a header use your API key instead: they send Authorization: Bearer <your-tarkle-key> to https://mcp.tarkle.com/mcp. For the setup of each assistant, see the MCP server developer docs.
Your plan and role
The API follows your organization's plan, the same way the app does. The plan sets the storage limit, the largest file you can upload, and how many Brand Pages and custom domains you can have. A call that goes over a limit is refused, as it is in the app. For what each plan includes, see Pricing and Brand Page plans and limits.
A key acts for the person who made it, and in each workspace it can do only what that person can do there.
Developer documentation
More detail for developers is in the developer docs: the API overview covers the endpoints for files, uploads, usage, Brand Pages and webhooks, and the MCP server docs cover AI assistants.