---
title: "API overview"
description: "Base URL, tokens, workspace keys, rate limits and versioning for the Tarkle API."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

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](/docs/get-started/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.

```bash
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/brands
```

## Scopes

`brands:read`, `brands:write`, `brands:create`, `brands:files`, `brands:domains`, `brands:requests`, `webhooks:manage`, `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](/docs/api/workspaces) | List the workspaces a token can use |
| [Files](/docs/api/files) | List, read, download, copy, rename, move, delete and restore |
| [Folders](/docs/api/folders) | Create folders |
| [Uploads](/docs/api/uploads) | Upload files of any size |
| [Usage](/docs/api/usage) | Storage use and limit |
| [Brand API](/docs/api/brands) | Read and change brand pages and handle access requests |
| [Not in the API yet](/docs/api/planned) | Product areas without endpoints, and what is planned |

## Conventions

- [Authentication](/docs/get-started/authentication): tokens, scopes and workspace keys.
- [Paging and limits](/docs/api/paging-and-limits): cursors, rate limit headers and versions.
- [Idempotency](/docs/api/idempotency): retry writes safely.

## Errors

Failures are `application/problem+json` documents. See [errors](/docs/api/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](/docs/mcp).

Source: https://tarkle.com/docs/api/index.mdx