The Tarkle API is JSON over HTTPS at https://tarkle.com/api/v1. It reads and changes brand pages, files and folders, uploads, webhooks and storage usage in the workspaces of your organization. This page maps the reference: where the machine-readable description is, the resource groups, the conventions every call follows and the AI route.
Base URL and the OpenAPI file
Every path in this reference is relative to https://tarkle.com/api/v1. The complete description is GET https://tarkle.com/api/v1/openapi.json, and it needs no key because it lists endpoints, not data. Each of the 48 operations has a unique operationId and a description, and the file groups them into five tags: Brands, Requests, Webhooks, Purchases and Files.
Authenticate
Send an API key from Settings > API as Authorization: Bearer <your-tarkle-key> on every call except the OpenAPI file. Only the owner and admins of an organization can create keys, and a key acts as the person who made it. See Authentication and API keys for the full rules.
A key is shown once when it is made. An owner or admin can copy it again from Settings > API. An older key can hold fewer permissions than a new one, and the MCP server does not accept it, so create a new key when you need the full set.
Name the workspace
Calls that read or change anything inside a workspace send its 8-character workspace key in the X-Workspace-Key header or the workspace_key query parameter. There is no default workspace, and a workspace id is refused with 400 workspace_key_required. GET /workspaces lists the workspaces the key reaches, with the key to send for each.
curl -H "Authorization: Bearer <your-tarkle-key>" https://tarkle.com/api/v1/workspaces
curl -H "Authorization: Bearer <your-tarkle-key>" -H "X-Workspace-Key: <workspace-key>" https://tarkle.com/api/v1/brandsWhat a key can do
A key holds every permission the API and the MCP server use except billing:purchase, so it reads and writes in each workspace it reaches. A key made for all workspaces reaches every workspace its creator can reach. A key made for selected workspaces reaches only those, and a call to any other workspace answers 403 no_access. Brand and webhook calls also need the person who made the key to be an owner or admin of that workspace. Purchase calls need billing:purchase, which no key holds, so they answer 403 forbidden.
Resource groups
The 48 operations fall into eight groups. Each group links to its page.
| Group | Operations | What it covers | Page |
|---|---|---|---|
| Workspaces | 1 | GET /workspaces: the workspaces the key reaches and the workspace key to send for each. |
Workspaces |
| Files and folders | 9 | List, read, find by path, download, create folders, rename or move, copy, delete to the bin and restore. | Files and Folders |
| Uploads | 5 | Start an upload, sign more part URLs, check it, complete it or abort it. | Uploads |
| Brands | 18 | Brand pages: read, create, update, archive and restore, domains, brand files, assets, brand.md, analytics and lookup from a website address. |
Brands |
| Requests | 2 | Download and view requests sent from a brand page: list them, approve or reject. | Access requests |
| Webhooks | 9 | Endpoints that receive signed events: create, change, test, rotate the secret, read deliveries and send an event again. | Webhooks |
| Purchases | 3 | Starts a plan purchase for an organization you own and completes it with a Stripe shared payment token. Keys do not hold billing:purchase. Live payments answer 503 agentic_commerce_not_enabled until Stripe approves them. |
OpenAPI file, no page of its own yet |
| Usage | 1 | GET /usage: storage in use and the plan’s limit in bytes. |
Usage |
| Transfers | 3 | A shareable link from files or folders already in the library: create, read and end one. The plain-file case only. | Transfers |
Conventions
- Idempotency. Send an
Idempotency-Keyheader of 1 to 255 visible characters with a POST, PATCH, PUT or DELETE. A repeat of the same request returns the first answer instead of doing it twice, and Tarkle keeps the key for 24 hours. Read Idempotency. - Paging and limits. A list returns one page. Send
limitand thecursorfromnext_cursorto get the next one. Brand lists take up to 100 items, with 25 by default, andGET /filestakes up to 1,000, with 100 by default. Every key has its own rate limit per minute: 120 requests for brand calls, and 600 for files calls andGET /workspaces. A429carriesRetry-Afterin seconds. Read Paging and limits. - Errors. Every error is an
application/problem+jsondocument with a stablecode. Branch oncode, and treat a code you do not know by its HTTP status. Read Errors. - Versions. Every response carries
X-Tarkle-Api-Version: v1. Inside v1 Tarkle only adds endpoints, optional parameters, response fields and error codes, so ignore what you do not know. A change that could break a client ships as a new version, and the old one keeps working for at least six months after its end is announced.
Flow
For the order of calls in a first integration, read API flow.
AI assistants
The MCP server accepts the same key. Coding assistants connect to https://mcp.tarkle.com/mcp with Authorization: Bearer <your-tarkle-key>. Assistants that sign in through the browser need no key.