--- title: "API overview" description: "The entry to the Tarkle API reference: base URL, the OpenAPI file, every resource group, API keys and the conventions." --- > 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`. 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 ` 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](/docs/get-started/authentication) and [API keys](/docs/get-started/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. ```bash curl -H "Authorization: Bearer " https://tarkle.com/api/v1/workspaces curl -H "Authorization: Bearer " -H "X-Workspace-Key: " https://tarkle.com/api/v1/brands ``` ## What 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](/docs/api/workspaces) | | Files and folders | 9 | List, read, find by path, download, create folders, rename or move, copy, delete to the bin and restore. | [Files](/docs/api/files) and [Folders](/docs/api/folders) | | Uploads | 5 | Start an upload, sign more part URLs, check it, complete it or abort it. | [Uploads](/docs/api/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](/docs/api/brands) | | Requests | 2 | Download and view requests sent from a brand page: list them, approve or reject. | [Access requests](/docs/api/brands/access-requests) | | Webhooks | 9 | Endpoints that receive signed events: create, change, test, rotate the secret, read deliveries and send an event again. | [Webhooks](/docs/api/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](https://tarkle.com/api/v1/openapi.json), no page of its own yet | | Usage | 1 | `GET /usage`: storage in use and the plan's limit in bytes. | [Usage](/docs/api/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](/docs/api/transfers) | ## Conventions - **Idempotency.** Send an `Idempotency-Key` header 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](/docs/api/idempotency). - **Paging and limits.** A list returns one page. Send `limit` and the `cursor` from `next_cursor` to get the next one. Brand lists take up to 100 items, with 25 by default, and `GET /files` takes 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 and `GET /workspaces`. A `429` carries `Retry-After` in seconds. Read [Paging and limits](/docs/api/paging-and-limits). - **Errors.** Every error is an `application/problem+json` document with a stable `code`. Branch on `code`, and treat a code you do not know by its HTTP status. Read [Errors](/docs/api/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](/docs/get-started/api-flow). ## AI assistants The [MCP server](/docs/mcp) accepts the same key. Coding assistants connect to `https://mcp.tarkle.com/mcp` with `Authorization: Bearer `. Assistants that sign in through the browser need no key. Source: https://tarkle.com/docs/api/index.mdx