The Tarkle API is JSON over HTTPS at https://tarkle.com/api/v1. The machine-readable description is GET https://tarkle.com/api/v1/openapi.json (no token needed). Every operation has a unique operationId and a description.
Authenticate
Create a token in Settings > API and send it as Authorization: Bearer tk_.... A token belongs to a person. On its own it can call GET /workspaces. See Authentication.
Name a workspace
To read or change anything inside a workspace, send its 8-character workspace key on every call: header X-Workspace-Key: <key> or query workspace_key. There is no default workspace. A workspace id is refused.
curl -H "Authorization: Bearer $TARKLE_TOKEN" https://tarkle.com/api/v1/workspaces
curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" https://tarkle.com/api/v1/brandsScopes
brands:read, brands:write, brands:requests, files:read, files:write. A token acts as the person who created it and never goes beyond that person’s role.
Rate limits
Brand endpoints: 120 requests a minute per token. Files endpoints: 600 a minute per token. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds). A 429 carries Retry-After in seconds.
Resources
| Page | What it covers |
|---|---|
| Workspaces | List the workspaces a token can use |
| Files | List, read, download, copy, rename, move, delete and restore |
| Folders | Create folders |
| Uploads | Upload files of any size |
| Usage | Storage use and limit |
| Brand API | Read and change brand pages and handle access requests |
| Not in the API yet | Product areas without endpoints, and what is planned |
Conventions
- Authentication: tokens, scopes and workspace keys.
- Paging and limits: cursors, rate limit headers and versions.
- Idempotency: retry writes safely.
Errors
Failures are application/problem+json documents. See errors.
Versioning
Every response carries X-Tarkle-Api-Version: v1. Additive fields can appear in v1. Breaking changes go to a new version (/api/v2), and the old version keeps working for at least six months after the deprecation notice.
CLI
A command line tool is planned. Until it exists, use the API directly or the MCP server.