> For the complete documentation index, see [llms.txt](https://project-03b42162.restlessdocs.com/llms.txt).

These are machine-readable instructions for using the Tarkle API.

Every endpoint, every parameter, every auth requirement - written for an agent that will copy-paste commands, not a human skimming for nouns.

# MCP Server

There's an MCP server at `https://project-03b42162.restlessdocs.com/mcp` exposing tools like `search_endpoints`, `get_endpoint`, and operation lookup. When you need specifics about an endpoint - parameters, status codes, examples - query the MCP server first; do not guess.

If the user has not yet connected the MCP server in their client, they can install it from the docs at `https://project-03b42162.restlessdocs.com`.

# Feedback

If this API or its docs were confusing, missing something, or behaved differently than documented, tell the maintainers so they can fix it. Send `POST https://project-03b42162.restlessdocs.com/feedback` with a JSON body:

```json
{"message": "what was confusing, missing, or broken", "requestIds": ["<x-request-id of the failed call>"]}
```

`message` is required. Optional: `context` (what you were trying to do), `subject` (the endpoint or doc it concerns), `email` (a contact address, only if you already have one), `requestIds` (ids from the `x-request-id` header or the end of an `x-log-url`, so the maintainer can open the exact log). Don't wait to be asked: if something slowed you down or blocked you, report it and carry on. Over MCP, the same note is the `send_feedback` tool.

# Getting Started

_No getting-started content yet. Add some at the dashboard's Getting Started page._

# Installation

## Use with Claude

Connect Tarkle to Claude Code, Claude Desktop, or Claude.ai over MCP, then let Claude search endpoints and make calls for you.

### Claude Code (CLI)

Run this from your terminal - Claude Code picks it up immediately.

```bash
claude mcp add --transport http tarkle-docs https://project-03b42162.restlessdocs.com/mcp
```

### Claude Desktop

Add this entry under `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then restart Claude Desktop.

```json
{
  "mcpServers": {
    "tarkle-docs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://project-03b42162.restlessdocs.com/mcp"
      ]
    }
  }
}
```

### Claude.ai (Web)

In Claude.ai, open Settings → Connectors → Add custom connector, then paste this URL. Available on paid plans.

```
https://project-03b42162.restlessdocs.com/mcp
```

Open Claude.ai: https://claude.ai/customize/connectors?modal=add-custom-connector

### Or paste this prompt

I want to use the Tarkle API.

If you support MCP (Model Context Protocol), connect to this server so you can search endpoints and make calls directly:
https://project-03b42162.restlessdocs.com/mcp

The full machine-readable documentation index is at https://project-03b42162.restlessdocs.com/llms.txt.
The complete OpenAPI spec is at https://project-03b42162.restlessdocs.com/openapi.yaml.
Read those, then help me make requests against the API.

## Use with ChatGPT

Use Tarkle from ChatGPT and the Codex CLI over MCP, so it can browse the API and write calls without you pasting docs.

### Codex (CLI)

Run this from your terminal - Codex (OpenAI's CLI) registers the MCP server immediately.

```bash
codex mcp add tarkle-docs --url https://project-03b42162.restlessdocs.com/mcp
```

### ChatGPT (Web)

In ChatGPT, open Settings → Connectors → Add, then paste this URL. Requires a paid plan with developer/connector access enabled.

```
https://project-03b42162.restlessdocs.com/mcp
```

Open ChatGPT: https://chatgpt.com/

### Or paste this prompt

I want to use the Tarkle API.

If you support MCP (Model Context Protocol), connect to this server so you can search endpoints and make calls directly:
https://project-03b42162.restlessdocs.com/mcp

The full machine-readable documentation index is at https://project-03b42162.restlessdocs.com/llms.txt.
The complete OpenAPI spec is at https://project-03b42162.restlessdocs.com/openapi.yaml.
Read those, then help me make requests against the API.

## Use with Any AI assistant

Point any MCP-compatible assistant at Tarkle, or hand it the docs directly.

### Install

Add this URL as a remote server in any MCP client. It works anywhere MCP over Streamable HTTP is supported, so there's nothing to install or run locally.

```
https://project-03b42162.restlessdocs.com/mcp
```

### Or paste this prompt

I want to use the Tarkle API.

If you support MCP (Model Context Protocol), connect to this server so you can search endpoints and make calls directly:
https://project-03b42162.restlessdocs.com/mcp

The full machine-readable documentation index is at https://project-03b42162.restlessdocs.com/llms.txt.
The complete OpenAPI spec is at https://project-03b42162.restlessdocs.com/openapi.yaml.
Read those, then help me make requests against the API.

## Node.js

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Node.js SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Node.js is fetch.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Python

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Python SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Python is requests.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Ruby

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Ruby SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Ruby is Net::HTTP.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## PHP

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official PHP SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for PHP is cURL.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Go

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Go SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Go is net/http.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## React

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official React SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for React is fetch.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Java

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Java SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Java is java.net.http.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## C#

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official C# SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for C# is HttpClient.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Rust

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no official Rust SDK, so use whatever HTTP client and conventions this codebase already uses for API calls. If there isn't an established pattern, a common choice for Rust is reqwest.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

## Any other language

### Agent setup prompt

We want to integrate Tarkle into this codebase via API.

There's no SDK, so use whatever HTTP client and conventions this codebase already uses for API calls.

Authentication: send a bearer token in the `Authorization` header (`Authorization: Bearer <token>`).

The base URL is `https://tarkle.com/api/v1`.

You can see the available endpoints at https://project-03b42162.restlessdocs.com/llms.txt, or read the full OpenAPI spec at https://project-03b42162.restlessdocs.com/openapi.yaml. Adapt the auth and endpoints to your use case as needed.

# Endpoints

Base URL: `https://tarkle.com/api/v1`

- List brands - `GET https://tarkle.com/api/v1/brands`
- Create a brand - `POST https://tarkle.com/api/v1/brands`
- Get a brand - `GET https://tarkle.com/api/v1/brands/{brand}`
- Delete a brand (archives it, restorable) - `DELETE https://tarkle.com/api/v1/brands/{brand}`
- Update a brand - `PATCH https://tarkle.com/api/v1/brands/{brand}`
- List archived brands - `GET https://tarkle.com/api/v1/archived-brands`
- Restore an archived brand - `POST https://tarkle.com/api/v1/archived-brands/{brand}/restore`
- Check a brand's domain - `GET https://tarkle.com/api/v1/brands/{brand}/domain`
- Connect a domain to a brand - `PUT https://tarkle.com/api/v1/brands/{brand}/domain`
- Remove a brand's domain - `DELETE https://tarkle.com/api/v1/brands/{brand}/domain`
- Look up a brand from its website address - `POST https://tarkle.com/api/v1/brand-lookup`
- Start uploading a brand file - `POST https://tarkle.com/api/v1/brands/{brand}/files`
- Remove a file from a brand - `DELETE https://tarkle.com/api/v1/brands/{brand}/files`
- Import a brand file from a web address - `POST https://tarkle.com/api/v1/brands/{brand}/files/import`
- Finish a brand file upload - `POST https://tarkle.com/api/v1/brands/{brand}/files/{file}/complete`
- List a brand's files with short-lived download links - `GET https://tarkle.com/api/v1/brands/{brand}/assets`
- The brand as markdown (brand.md) - `GET https://tarkle.com/api/v1/brands/{brand}/markdown`
- Page views, downloads and requests - `GET https://tarkle.com/api/v1/brands/{brand}/analytics`
- List download and view requests - `GET https://tarkle.com/api/v1/brands/{brand}/requests`
- List the files and folders inside a folder of the library (folders first, then files; the root by default) - `GET https://tarkle.com/api/v1/files`
- Get one file or folder, with its path and whether it is protected - `GET https://tarkle.com/api/v1/files/{id}`
- Rename and/or move a file or folder, and/or set a file's own modification time (body: name, parent_id: a folder id or null for the root, modified_at) - `PATCH https://tarkle.com/api/v1/files/{id}`
- Move a file or folder to the bin; if a transfer holds it, 409 transfer_active until confirm_delete_transfers=true - `DELETE https://tarkle.com/api/v1/files/{id}`
- A short-lived download link for a file - `GET https://tarkle.com/api/v1/files/{id}/download`
- Search the words inside the library's files; returns the best matching passages with file id, page and a snippet - `GET https://tarkle.com/api/v1/files/search`
- Ask a question about the files and get an answer with sources (body: question, folder, mode) - `POST https://tarkle.com/api/v1/ai/ask`
- The text of one file, by page range (about 12,000 characters per call) - `GET https://tarkle.com/api/v1/files/{id}/text`
- Create a folder (body: name, parent_id optional; a taken name is a 409) - `POST https://tarkle.com/api/v1/folders`
- The workspaces this token can be used for, with the workspace_key to send as X-Workspace-Key (needs any API access) - `GET https://tarkle.com/api/v1/workspaces`
- One file or folder by its path, without listing the folder around it (404 not found, 409 ambiguous_path) - `GET https://tarkle.com/api/v1/files/by-path`
- Restore a file or folder from the bin (same retention rule as the app) - `POST https://tarkle.com/api/v1/files/{id}/restore`
- Copy a file inside storage (body: parent_id, name; a taken name is 409, plan limits apply) - `POST https://tarkle.com/api/v1/files/{id}/copy`
- Page tools on a PDF, saved as a new PDF (merge, keep or remove, reorder, rotate, crop, blank pages, page numbers, watermark, title and author) - `POST https://tarkle.com/api/v1/files/{id}/pdf-edit`
- Convert a file into a new file (PDF to text, pictures, Word, Excel or split parts; pictures or an Office file to PDF; OCR, redact, compress, protect, unlock) - `POST https://tarkle.com/api/v1/files/{id}/convert`
- Write a new document from content (PDF, Word, PowerPoint, Excel, CSV or Markdown) - `POST https://tarkle.com/api/v1/documents`
- Fill a Word template into a new .docx ({placeholders}, lists, repeated table rows) - `POST https://tarkle.com/api/v1/files/{id}/fill-template`
- Change a copy of a Word, PowerPoint or Excel file (replace text, insert, change cells, append rows) - `POST https://tarkle.com/api/v1/files/{id}/office-edit`
- Storage in use and the plan's limit (null when there is none) - `GET https://tarkle.com/api/v1/usage`
- Start an upload into a folder (body: name, size, folder_id, content_type, sha256, on_conflict); returns signed URLs, or creates an empty file directly when size is 0 - `POST https://tarkle.com/api/v1/uploads`
- Where an upload stands (never finishes it) - `GET https://tarkle.com/api/v1/uploads/{id}`
- Abort an unfinished upload - `DELETE https://tarkle.com/api/v1/uploads/{id}`
- Fresh signed URLs for a range of parts (from_part, count up to 100) - `POST https://tarkle.com/api/v1/uploads/{id}/parts`
- Finish the upload into the folder chosen at the start; optional body: sha256, modified_at (multipart_id is stored by the server); returns the file - `POST https://tarkle.com/api/v1/uploads/{id}/complete`
- Approve or reject a request - `POST https://tarkle.com/api/v1/brands/{brand}/requests/{request}`
- List webhook endpoints - `GET https://tarkle.com/api/v1/webhooks`
- Add a webhook endpoint - `POST https://tarkle.com/api/v1/webhooks`
- Get a webhook endpoint - `GET https://tarkle.com/api/v1/webhooks/{id}`
- Change a webhook endpoint - `PATCH https://tarkle.com/api/v1/webhooks/{id}`
- Delete a webhook endpoint - `DELETE https://tarkle.com/api/v1/webhooks/{id}`
- Rotate the signing secret - `POST https://tarkle.com/api/v1/webhooks/{id}/rotate-secret`
- Send a test event - `POST https://tarkle.com/api/v1/webhooks/{id}/test`
- List an endpoint's deliveries - `GET https://tarkle.com/api/v1/webhooks/{id}/deliveries`
- Send an event again - `POST https://tarkle.com/api/v1/webhooks/{id}/deliveries/{delivery}/redeliver`
- Create a shareable transfer link - `POST https://tarkle.com/api/v1/transfers`
- Get a transfer - `GET https://tarkle.com/api/v1/transfers/{id}`
- End a transfer early - `DELETE https://tarkle.com/api/v1/transfers/{id}`
- Change a transfer: view only, expiry or password - `PATCH https://tarkle.com/api/v1/transfers/{id}`
- Share a folder of photos as a gallery, free or paid (body: folder_id, title, price, currency, preview_mode, preview_count, watermark, client_name, client_email) - `POST https://tarkle.com/api/v1/galleries`
- Get a gallery, its links and who paid - `GET https://tarkle.com/api/v1/galleries/{id}`
- Deliver a transfer to contacts' client portals - `POST https://tarkle.com/api/v1/transfers/{id}/contacts`
- Add a contact - `POST https://tarkle.com/api/v1/contacts`
- List contacts - `GET https://tarkle.com/api/v1/contacts`
- Turn client portal access on or off - `POST https://tarkle.com/api/v1/contacts/{id}/portal-access`
- Resend a contact's portal sign-in email - `POST https://tarkle.com/api/v1/contacts/{id}/portal-invite`
- Set a contact's portal upload limit - `POST https://tarkle.com/api/v1/contacts/{id}/storage-limit`
- Read a contact's portal upload limit and use - `GET https://tarkle.com/api/v1/contacts/{id}/storage-limit`
- Create a file request - `POST https://tarkle.com/api/v1/file-requests`
- List file requests - `GET https://tarkle.com/api/v1/file-requests`
- List team folders - `GET https://tarkle.com/api/v1/teams`
- Create a team folder - `POST https://tarkle.com/api/v1/teams`

## Full OpenAPI specification

Complete spec for every endpoint above (internal operations removed):

```yaml
openapi: 3.1.0
info:
  title: Tarkle API
  version: v1
  summary: Brands, files, uploads and storage usage for Tarkle workspaces
  description: >-
    Public API for Tarkle workspaces: brands, files and folders, uploads, storage usage and the
    workspaces a token can reach.


    **Start.** Create a token in Settings > API and send it as `Authorization: Bearer tk_...`. A
    token works for every workspace its creator can use. Call GET /workspaces to list them, then
    send the workspace's 8-character key in the `X-Workspace-Key` header (or the `workspace_key`
    query parameter) on every other call.


    **Scopes.** `brands:read` (Read brands, their assets, brand.md and analytics); `brands:write`
    (Update a brand's text, links, access and settings); `brands:create` (Create brands, delete them
    to the bin and restore them from it); `brands:domains` (Connect, check and remove a brand's
    custom domain); `brands:files` (Upload a brand's icon, logos, banner, social image, favicon and
    collection files); `brands:requests` (List download and view requests and approve or reject
    them); `webhooks:manage` (Add, change and remove webhook endpoints, send test events and read
    the delivery log); `files:read` (List and download files and folders); `files:write` (Create
    folders, rename and delete files and folders (and restore them from the bin); uploads are
    separate endpoints); `ai:ask` (Ask a question about the library's files and get an answer with
    sources; it spends AI credits like a question in Ask about files (read-only));
    `transfers:create` (Create a shareable transfer link from files or folders already in the
    library, deliver it to contacts' client portals, change it (view only, expiry, password) and
    delete it); `transfers:read` (Read a transfer's status); `contacts:create` (Add a contact to the
    workspace); `contacts:read` (List and search the workspace's contacts, and read their portal
    upload use); `contacts:portal` (Turn a contact's client portal access on or off, resend their
    sign-in email and set their portal upload limit); `file_requests:create` (Create a public upload
    link (a file request)); `file_requests:read` (List the workspace's file requests);
    `teams:create` (Create a team folder (Pro only, owner or admin)). Each operation lists the scope
    it needs in `x-required-scope` and in its `security` requirement. Every API key made in Settings
    > API holds every scope and is limited only by the workspaces it may reach; there is no OAuth
    flow for this API (the OAuth login of the MCP server does not issue tokens for it), so no oauth2
    scheme is declared.


    **Limits.** Three limits follow the organization's plan (Free, Pro, Agency). Per API key: 50 /
    250 / 500 requests a minute, and 5 / 25 / 50 search and AI requests a minute (GET /files/search,
    POST /brand-lookup, POST /ai/ask; they also count in the first limit). Per organization, shared
    by all its keys and workspaces: 2,500 / 25,000 / 100,000 requests a day (resets at midnight
    UTC); a request costs 1, a search 5. Reseller has the Agency numbers and Reseller Pro double
    them (1,000 and 100 a minute per key, 200,000 a day); a lifetime plan gets half of its plan's
    per-minute and daily numbers. Read the numbers from the headers instead of hard-coding them.
    Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
    `X-RateLimit-Reset` (Unix seconds) for the minute, the IETF forms `RateLimit-Limit`,
    `RateLimit-Remaining`, `RateLimit-Reset` (seconds left) and `RateLimit-Policy` (for example
    250;w=60, 25000;w=86400), and `X-Quota-Limit`, `X-Quota-Remaining` and `X-Quota-Reset` (Unix
    seconds) for the day. From 80% of the day `X-Quota-Warning: 80%` is added. A 429 adds
    `Retry-After` (seconds): code `rate_limited` when a per-minute limit was hit, code
    `quota_exceeded` when the day is used up (wait until midnight UTC). A refused request costs no
    quota. A 401 and this document carry the minute headers for the caller's IP bucket (60 a
    minute), which only reports and refuses nothing. Keys made before 2026-11-15 keep the earlier
    limits (120 a minute on brand operations, 600 on files operations, no daily quota refusal) until
    2026-12-13.


    **Errors.** Every error is a problem details object (RFC 9457) with the content type
    `application/problem+json`: `type`, `title`, `status`, `detail` and a stable `code` to branch
    on. The older `error: { code, message }` envelope is still included. `x-error-codes` lists every
    code with its status and meaning.


    **Safe repeats.** Send `Idempotency-Key` (any random value up to 255 characters) with a POST,
    PATCH, PUT or DELETE and a repeat of the same request returns the first answer instead of doing
    it twice. See the header's description for the rules.


    **Versioning.** The version is in the path (`/api/v1`). Inside v1 we only add things: endpoints,
    optional parameters, response fields and error codes, so ignore fields and codes 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 6 months after we announce its end, with `Deprecation` (RFC 9745) and `Sunset` (RFC
    8594) headers, plus a `Link` with rel deprecation or sunset, on its responses during that time.
    No version is deprecated today, so those headers do not appear yet (see `x-api-lifecycle`).


    Guides and examples: https://tarkle.com/docs/api/brands
  termsOfService: https://tarkle.com/terms
  contact:
    name: Tarkle support
    email: support@tarkle.tech
    url: https://tarkle.com/contact
externalDocs:
  description: Tarkle API guides
  url: https://tarkle.com/docs/api/brands
servers:
  - url: https://tarkle.com/api/v1
tags:
  - name: Brands
    description: >-
      Read and update brand pages, their assets, brand.md and analytics. The token's creator must be
      an owner or admin of the workspace.
  - name: Requests
    description: Download and view requests people send from a brand page, and your decision on them.
  - name: Webhooks
    description: >-
      Tarkle sends signed events to addresses you register. Each delivery is a POST of the
      WebhookEvent object with the headers Tarkle-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of
      "<t>.<raw body>" with your endpoint's secret>, one v1 per secret in force), Tarkle-Event,
      Tarkle-Event-Id and Tarkle-Delivery. Check the signature on the raw body and reject a
      timestamp more than 5 minutes old. Events: brand.viewed (only when an endpoint names it; "all
      events" does not include page views), brand.downloaded (the file, never the visitor),
      brand.updated (the names of what changed), brand.request.created, brand.request.approved and
      brand.request.rejected (who asked: name, company, email). Answer with any 2xx within 10
      seconds. Otherwise Tarkle retries up to 8 times over about 24 hours; an endpoint that keeps
      failing is switched off and the owner is emailed. Redirects are not followed and addresses on
      private networks are refused. The token's creator must be an owner or admin of the workspace.
  - name: Files
    description: >-
      The workspace library: list, read, download, create folders, rename, move, copy, delete and
      restore; uploads, including multipart; storage usage; and the workspaces a token can act on.
  - name: Transfers
    description: >-
      Shareable links from files or folders already in the library -- a plain file transfer, the
      same kind the app's own send flow creates. No video, audio or canvas transfers, no payment and
      no recipient emails through this endpoint; create one, read its status, or delete it early.
  - name: Galleries
    description: >-
      A folder of photos shared as a gallery: free, or paid with watermarked previews and a checkout
      link (pay_url) the buyer pays through with PayPal or card, whichever the workspace connected.
      Getting paid needs Pro and PayPal or Stripe connected in Settings > Integrations.
  - name: Contacts
    description: >-
      The workspace's clients (customers you share files with). Add one, list and search existing
      contacts, and turn client portal access on or off. Organizations are created as a side effect
      of adding a contact with an organization name.
  - name: File requests
    description: >-
      A public upload link that collects files from anyone who opens it. Create one, or list
      existing requests.
  - name: Teams
    description: >-
      Team folders: Pro-only shared folders with their own storage budget. Only an owner or admin
      may create one.
components:
  schemas:
    Problem:
      type: object
      description: >-
        A problem details object (RFC 9457), sent as application/problem+json on every error. Branch
        on code, not on detail: code is stable, detail is for people and can change.
      properties:
        type:
          type: string
          format: uri
          description: >-
            Identifies the problem: https://tarkle.com/docs/api/errors/<code>. Treat it as an
            identifier
        title:
          type: string
          description: A short, fixed summary of the problem type
        status:
          type: integer
          description: The HTTP status code, repeated for clients that lose the response line
        detail:
          type: string
          description: What went wrong this time, in plain words
        code:
          type: string
          description: >-
            A stable machine-readable code such as not_found or name_taken. Every code is listed in
            x-error-codes. v1 can add codes, so treat one you do not know by its HTTP status
        details:
          type: object
          additionalProperties: true
          description: Extra members for some codes; x-details-by-code says which schema each uses
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
          description: >-
            The envelope older clients read: the same code, with detail as message. Prefer the
            top-level members
      required:
        - type
        - title
        - status
        - detail
        - code
        - error
      x-details-by-code:
        conflict:
          $ref: '#/components/schemas/ConflictDetails'
        empty_version_not_supported:
          $ref: '#/components/schemas/ChoicesDetails'
        incomplete:
          $ref: '#/components/schemas/IncompleteDetails'
        transfer_active:
          $ref: '#/components/schemas/TransferActiveDetails'
        protected:
          $ref: '#/components/schemas/ProtectedDetails'
    ConflictDetails:
      type: object
      properties:
        reason:
          type:
            - string
            - 'null'
          description: Why the app would ask, for example file_in_transfer
        existing:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
            - type: 'null'
          description: The file that holds the name
        answer_with:
          type: string
          enum:
            - on_conflict
          description: The request field that carries your answer
        choices:
          type: array
          items:
            type: string
            enum:
              - version
              - separate
              - skip
      required:
        - reason
        - existing
        - answer_with
        - choices
    ChoicesDetails:
      type: object
      properties:
        choices:
          type: array
          items:
            type: string
            enum:
              - separate
              - skip
      required:
        - choices
    IncompleteDetails:
      type: object
      properties:
        parts_received:
          type: integer
        parts_needed:
          type: integer
        missing_parts:
          type: array
          items:
            type: integer
          description: The part numbers still to send (at most 1000 are listed)
        missing_parts_truncated:
          type: boolean
          description: Present and true when more parts are missing than listed
      required:
        - parts_received
        - parts_needed
        - missing_parts
    TransferRef:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
        title:
          type:
            - string
            - 'null'
      required:
        - id
    TransferActiveDetails:
      type: object
      properties:
        transfers:
          type: array
          items:
            $ref: '#/components/schemas/TransferRef'
        needs_confirmation:
          type: boolean
          description: True when repeating the call with the confirmation would delete those transfers
        needs_token_setting:
          type: boolean
          description: True when the token's settings do not allow deleting transfers
        confirm_with:
          type: string
          description: The query parameter that confirms the delete
      required:
        - transfers
        - needs_confirmation
        - needs_token_setting
        - confirm_with
    ProtectedDetails:
      type: object
      properties:
        kind:
          type:
            - string
            - 'null'
        transfers:
          type: array
          items:
            $ref: '#/components/schemas/TransferRef'
      required:
        - kind
    BrandSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        summary:
          type: string
        access:
          type: string
          enum:
            - public
            - password
            - restricted
          description: >-
            public: anyone; password: anyone with the password; restricted: only people assigned to
            the brand
        is_draft:
          type: boolean
        download_approval:
          type: boolean
        indexable:
          type: boolean
        created_at:
          type: string
          format: date-time
        urls:
          type: object
          properties:
            page:
              type: string
            api:
              type: string
          required:
            - page
            - api
      required:
        - id
        - slug
        - name
        - summary
        - access
        - is_draft
        - download_approval
        - indexable
        - created_at
        - urls
    BrandList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BrandSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - data
        - next_cursor
    BrandFont:
      type: object
      properties:
        name:
          type: string
        custom:
          type: boolean
        source:
          type: string
          enum:
            - google
            - adobe
            - custom
        css:
          type: string
      required:
        - name
        - custom
        - source
    Brand:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        summary:
          type: string
        story:
          type: string
        industry:
          type: string
        size:
          type: string
        company_type:
          type: string
        year_founded:
          type: string
        website:
          type: string
        social:
          type: object
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
          required:
            - twitter
            - facebook
            - instagram
            - linkedin
            - youtube
            - github
        colors:
          type: object
          properties:
            primary:
              type:
                - string
                - 'null'
            secondary:
              type:
                - string
                - 'null'
            additional:
              type: array
              items:
                type: object
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                  value:
                    type: string
                required:
                  - name
                  - value
          required:
            - primary
            - secondary
            - additional
        fonts:
          type: object
          properties:
            headline:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BrandFont'
            body:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BrandFont'
          required:
            - headline
            - body
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values entered for a color, keyed by the color's hex
        auto_logo_variants:
          type: boolean
          description: Whether black and white logo downloads are made automatically
        access:
          type: string
          enum:
            - public
            - password
            - restricted
          description: >-
            public: anyone; password: anyone with the password; restricted: only people assigned to
            the brand
        is_draft:
          type: boolean
        download_approval:
          type: boolean
        indexable:
          type: boolean
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          required:
            - ga4
            - gtm
            - search_console
            - adobe_kit
        seo:
          type: object
          properties:
            title:
              type:
                - string
                - 'null'
            description:
              type:
                - string
                - 'null'
          required:
            - title
            - description
        team:
          type: object
          properties:
            title:
              type: string
            members:
              type: array
              items:
                type: object
                properties:
                  id:
                    type:
                      - string
                      - 'null'
                  name:
                    type: string
                  title:
                    type: string
                  has_photo:
                    type: boolean
                required:
                  - id
                  - name
                  - title
                  - has_photo
          required:
            - title
            - members
        press:
          type: array
          items:
            type: object
            properties:
              id:
                type:
                  - string
                  - 'null'
              title:
                type: string
              url:
                type: string
              description:
                type: string
              image:
                type: string
              source:
                type: string
            required:
              - id
              - title
              - url
              - description
              - image
              - source
        guidelines:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              text:
                type: string
              images:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                  required:
                    - id
                    - kind
                    - caption
            required:
              - id
              - title
              - text
              - images
        urls:
          type: object
          properties:
            page:
              type: string
            markdown:
              type: string
            mark_usage:
              type: string
            api:
              type: string
          required:
            - page
            - markdown
            - mark_usage
            - api
        created_at:
          type: string
          format: date-time
        pictures:
          type: array
          description: >-
            Only in the answer of a create or update that named pictures by address: one entry per
            picture, ok true or false with the reason
          items:
            type: object
            properties:
              picture:
                type: string
                enum:
                  - team_photo
                  - guideline_image
              target:
                type: string
              ok:
                type: boolean
              error:
                type: string
            required:
              - picture
              - target
              - ok
      required:
        - id
        - slug
        - name
        - summary
        - story
        - industry
        - size
        - company_type
        - year_founded
        - website
        - social
        - colors
        - fonts
        - print_values
        - auto_logo_variants
        - access
        - is_draft
        - download_approval
        - indexable
        - tracking
        - seo
        - team
        - press
        - guidelines
        - urls
        - created_at
    BrandCreate:
      type: object
      additionalProperties: false
      required:
        - name
        - summary
        - industry
      description: >-
        A brand needs a name, a summary and an industry from the list. Everything else is optional
        and uses the same fields as updateBrand, so a brand can be created complete in one call
        (colors, fonts, team, press, guidelines, tracking). Text limits are the app's (name 48,
        summary 200, story 2000 characters); longer values are refused. A new brand is a private
        draft. access, is_draft and confirm_public are not accepted here; use updateBrand
        afterwards. If a part cannot be saved the brand is not created.
      properties:
        summary:
          type: string
          maxLength: 200
        story:
          type: string
          maxLength: 2000
        size:
          type: string
          enum:
            - ''
            - 1 employee
            - 2-10 employees
            - 11-50 employees
            - 51-200 employees
            - 201-500 employees
            - 501-1000 employees
            - 1001-5000 employees
            - 5001-10,000 employees
            - 10,001+ employees
        company_type:
          type: string
          enum:
            - ''
            - Educational
            - Government Agency
            - Non-Profit
            - Partnership
            - Privately Held
            - Public Company
            - Self-Employed
            - Self-Owned
        year_founded:
          type:
            - string
            - integer
          description: A four digit year, or empty to clear
        url:
          type: string
          description: A public website address, or empty to clear. Same as website
        website:
          type: string
          description: Same as url
        twitter:
          type: string
        facebook:
          type: string
        instagram:
          type: string
        linkedin:
          type: string
        youtube:
          type: string
        github:
          type: string
        social:
          type: object
          additionalProperties: false
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
        primary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
        colors:
          type: object
          additionalProperties: false
          description: >-
            primary, secondary and the extra colors. additional replaces the whole extra list (up to
            30); sending only one of secondary or additional keeps the other as it is
          properties:
            primary:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            secondary:
              type:
                - string
                - 'null'
              pattern: ^#[0-9a-fA-F]{3,8}$
            additional:
              type: array
              maxItems: 30
              items:
                type: object
                required:
                  - value
                additionalProperties: false
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                    maxLength: 60
                  value:
                    type: string
                    pattern: ^#[0-9a-fA-F]{3,8}$
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values per color hex, as GET returns them (up to 40)
        auto_logo_variants:
          type: boolean
          description: Make black and white logo downloads automatically
        fonts:
          type: object
          additionalProperties: false
          description: >-
            headline and body font, each { source: google | adobe, name } or null to clear. A Google
            name must be a Google Fonts family (checked). Adobe also needs css (the family's CSS
            name) and tracking.adobe_kit. A custom font is a file uploaded in the app; the API does
            not set one.
          properties:
            headline:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
            body:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
        team:
          type: object
          additionalProperties: false
          description: >-
            The people section: a heading (up to 30 characters) and up to 24 members. A photo is
            kept for a member you send again; photo_url sets or replaces it
          properties:
            title:
              type: string
              maxLength: 30
            members:
              type: array
              maxItems: 24
              items:
                type: object
                required:
                  - name
                additionalProperties: false
                properties:
                  id:
                    type: string
                  name:
                    type: string
                    maxLength: 80
                  title:
                    type: string
                    maxLength: 80
                  photo_url:
                    type: string
                    description: A public https image address for the photo; fetched after the text is saved
        press:
          type: array
          maxItems: 24
          items:
            type: object
            required:
              - url
            additionalProperties: false
            properties:
              id:
                type: string
              url:
                type: string
                description: A public page address
              title:
                type: string
                maxLength: 200
              description:
                type: string
                maxLength: 300
              image:
                type: string
                description: A public image address shown with the article
              source:
                type: string
                maxLength: 100
          description: Articles written about the brand
        guidelines:
          type: array
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
              title:
                type: string
                maxLength: 80
              text:
                type: string
                description: 'Plain text: blank line between paragraphs, ''- '' for bullets, ''## '' for a heading'
              images:
                type: array
                maxItems: 12
                description: >-
                  Pictures to add to the section, fetched after the text is saved (an entry without
                  url is ignored, so a read can be sent back)
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                    url:
                      type: string
                      description: A public https image address
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                      maxLength: 200
          description: >-
            Guideline sections (up to 20). Existing section images stay for a section you send again
            with its id; images adds more
        download_approval:
          type: boolean
        seo:
          type: object
          additionalProperties: false
          properties:
            title:
              type: string
              maxLength: 100
            description:
              type: string
              maxLength: 160
        meta_title:
          type: string
          maxLength: 100
        meta_description:
          type: string
          maxLength: 160
        team_title:
          type: string
          maxLength: 30
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          additionalProperties: false
          description: >-
            Google Analytics 4 id (G-...), Tag Manager id (GTM-...), Search Console token and Adobe
            Fonts project. Only the keys sent change
        name:
          type: string
          minLength: 1
          maxLength: 48
        slug:
          type: string
          maxLength: 48
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          description: Defaults to the name
        password:
          type: string
          minLength: 8
          description: >-
            Protects the brand with a password from the start (API only: the MCP never takes one). 8
            characters at least, 72 bytes at most. Stored hashed and never returned; the brand shows
            access password. It cannot be changed here afterwards; going public removes it
        industry:
          type: string
          enum:
            - Arts and Entertainment
            - Business and Consumer Services
            - Community and Society
            - Computer Electronics and Technology
            - E-commerce and Shopping
            - Finance
            - Food and Drink
            - Gambling
            - Games
            - Health
            - Heavy Industry and Engineering
            - Hobbies and Leisure
            - Home and Garden
            - Jobs and Career
            - Law and Government
            - Lifestyle
            - Luxury
            - News and Media
            - Pets and Animals
            - Reference Materials
            - Science and Education
            - Sports
            - Travel and Tourism
            - Vehicles
    BrandFileStart:
      type: object
      additionalProperties: false
      required:
        - slot
      properties:
        slot:
          type: string
          enum:
            - icon
            - main_logo
            - banner
            - social_image
            - favicon
            - logo
            - asset
            - team_photo
            - guideline_image
        size:
          type: integer
          minimum: 1
          description: The file's size in bytes; refused early when over the slot's limit
        filename:
          type: string
          maxLength: 255
          description: The file's name; refused early when its extension is not allowed for the slot
    BrandFileUpload:
      type: object
      properties:
        file_id:
          type: string
        slot:
          type: string
        upload:
          type: object
          properties:
            method:
              type: string
              enum:
                - PUT
            url:
              type: string
            expires_in:
              type: integer
          required:
            - method
            - url
            - expires_in
        max_bytes:
          type: integer
        extensions:
          type:
            - array
            - 'null'
          items:
            type: string
          description: 'null: any type'
        complete_url:
          type: string
      required:
        - file_id
        - slot
        - upload
        - max_bytes
        - extensions
        - complete_url
    BrandFileComplete:
      type: object
      additionalProperties: false
      description: >-
        Empty for icon, main_logo, banner, social_image and favicon. For logo: name, type, usage.
        For asset: collection_id or collection_name, name, type. For team_photo: member_id or
        member_name. For guideline_image: section_id, kind, caption.
      properties:
        name:
          type: string
          maxLength: 120
        type:
          type: string
          maxLength: 100
          description: >-
            For logo: primary, secondary, monochrome, reversed, icon, favicon, square or social
            media. For asset: the file type, for example image/png
        usage:
          type: string
          enum:
            - digital
            - print
            - all purpose
        collection_id:
          type: string
          format: uuid
        collection_name:
          type: string
          maxLength: 80
        member_id:
          type: string
        member_name:
          type: string
          maxLength: 80
        section_id:
          type: string
        kind:
          type: string
          enum:
            - image
            - do
            - dont
        caption:
          type: string
          maxLength: 200
    BrandFileImport:
      type: object
      additionalProperties: false
      required:
        - slot
        - url
      description: >-
        slot and url, plus for logo: name, type, usage; for asset: collection_id or collection_name,
        name, type; for team_photo: member_id or member_name; for guideline_image: section_id, kind,
        caption.
      properties:
        slot:
          type: string
          enum:
            - icon
            - main_logo
            - banner
            - social_image
            - favicon
            - logo
            - asset
            - team_photo
            - guideline_image
        url:
          type: string
          description: The https address of a public image
        name:
          type: string
          maxLength: 120
        type:
          type: string
          maxLength: 100
        usage:
          type: string
          enum:
            - digital
            - print
            - all purpose
        collection_id:
          type: string
          format: uuid
        collection_name:
          type: string
          maxLength: 80
        member_id:
          type: string
        member_name:
          type: string
          maxLength: 80
        section_id:
          type: string
        kind:
          type: string
          enum:
            - image
            - do
            - dont
        caption:
          type: string
          maxLength: 200
    BrandFileAttached:
      type: object
      properties:
        slot:
          type: string
        file_id:
          type: string
        size:
          type:
            - integer
            - 'null'
        already_attached:
          type: boolean
        logo_id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        asset_file_id:
          type: string
          format: uuid
        member_id:
          type: string
        section_id:
          type: string
        image_id:
          type: string
      required:
        - slot
        - file_id
        - size
        - already_attached
    BrandFileRemoved:
      type: object
      properties:
        removed:
          type: object
          properties:
            slot:
              type: string
            removed_id:
              type:
                - string
                - 'null'
          required:
            - slot
            - removed_id
      required:
        - removed
    DnsRecord:
      type: object
      properties:
        type:
          type:
            - string
            - 'null'
        host:
          type:
            - string
            - 'null'
        value:
          type:
            - string
            - 'null'
        purpose:
          type:
            - string
            - 'null'
        status:
          type: string
      required:
        - type
        - host
        - value
        - purpose
        - status
    BrandDomain:
      type: object
      properties:
        id:
          type: string
          format: uuid
        brand_id:
          type: string
          format: uuid
        domain:
          type: string
        status:
          type: string
          enum:
            - ownership_verification_required
            - dns_configuration_required
            - certificate_pending
            - active
          description: >-
            Where the setup stands. Add the dns_records at your DNS host; active means the domain
            serves the brand page
        status_message:
          type: string
        certificate_status:
          type:
            - string
            - 'null'
        dns_records:
          type: array
          items:
            $ref: '#/components/schemas/DnsRecord'
        last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        provider_unavailable:
          type: boolean
          description: >-
            Only on getBrandDomain: true when the hosting provider could not be reached and the
            stored values are shown
        dns_provider:
          anyOf:
            - type: 'null'
            - type: object
              additionalProperties: false
              required:
                - id
                - name
                - dashboard_url
                - nameservers
              properties:
                id:
                  type:
                    - string
                    - 'null'
                name:
                  type:
                    - string
                    - 'null'
                dashboard_url:
                  type:
                    - string
                    - 'null'
                nameservers:
                  type: array
                  items:
                    type: string
          description: >-
            Who hosts the DNS of the domain, found from its nameservers (Cloudflare, Vercel, Route
            53, GoDaddy and others). id and name are null when the host is not recognised. null when
            the nameservers could not be read
        dns_zone:
          type:
            - string
            - 'null'
          description: >-
            The DNS zone the records belong in (for brand.example.com usually example.com). null
            when it could not be found
        dns_guide:
          type: object
          description: >-
            Ready-made instructions to finish the setup by hand or by a tool that can edit DNS.
            Records are named relative to dns_zone
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  name:
                    type: string
                  fqdn:
                    type: string
                  value:
                    type: string
                  ttl:
                    type: integer
                  proxied:
                    type: boolean
                  purpose:
                    type:
                      - string
                      - 'null'
                  status:
                    type: string
                required:
                  - type
                  - name
                  - fqdn
                  - value
                  - ttl
                  - proxied
                  - purpose
                  - status
            steps:
              type: array
              items:
                type: string
            apply_with:
              type: array
              items:
                type: object
                properties:
                  tool:
                    type: string
                  how:
                    type: string
                required:
                  - tool
                  - how
            verify:
              type: object
              properties:
                method:
                  type: string
                path:
                  type: string
                poll_every_seconds:
                  type: integer
                done_when:
                  type: string
                note:
                  type: string
              required:
                - method
                - path
                - poll_every_seconds
                - done_when
                - note
            notes:
              type: array
              items:
                type: string
      required:
        - id
        - brand_id
        - domain
        - status
        - status_message
        - certificate_status
        - dns_records
        - last_checked_at
        - created_at
    BrandDomainSet:
      type: object
      additionalProperties: false
      required:
        - domain
      properties:
        domain:
          type: string
          description: A hostname such as brand.example.com (no path, port or spaces)
    BrandDomainDeleted:
      type: object
      properties:
        deleted:
          type: boolean
        domain:
          type: string
      required:
        - deleted
        - domain
    BrandLookupRequest:
      type: object
      additionalProperties: false
      required:
        - domain
      properties:
        domain:
          type: string
          description: A public website name or address such as acme.com or https://www.acme.com
    BrandLookup:
      type: object
      properties:
        domain:
          type: string
        brand:
          $ref: '#/components/schemas/BrandCreate'
          description: >-
            Suggested fields, in the shape createBrand and updateBrand take. Only fields that were
            found are present; name is always present
        files:
          type: object
          additionalProperties: false
          properties:
            main_logo:
              type: string
            icon:
              type: string
            banner:
              type: string
          description: >-
            Public picture addresses found for the brand. Import one with the brand file upload
            (import_url)
        sources:
          type: object
          additionalProperties:
            type: string
          description: Which provider gave each value (brandfetch, context.dev, logo.dev or site)
        missing:
          type: array
          items:
            type: string
          description: Fields and files that were not found
      required:
        - domain
        - brand
        - files
        - sources
        - missing
    ArchivedBrand:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        archived_at:
          type: string
          format: date-time
        domains:
          type: array
          items:
            type: string
      required:
        - id
        - slug
        - name
        - archived_at
        - domains
    ArchivedBrandList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ArchivedBrand'
      required:
        - data
    BrandRestore:
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          maxLength: 48
          description: Another address, when the old one is used now
    BrandPatch:
      type: object
      additionalProperties: false
      minProperties: 1
      description: >-
        Send only what changes. Every field GET /brands/{brand} returns can be sent back in the same
        shape (colors, social, seo, team, website, fonts), and the older flat names (primary_color,
        twitter, meta_title, team_title, url) still work. A list you send replaces the stored list
        (colors.additional, team.members, press, guidelines). Logos, the banner and collection files
        go through the files endpoints; team photos and guideline images can also be sent by address
        (photo_url, images) and are kept when you resend the same team member or guideline section.
        The slug, passwords and custom fonts cannot be changed here. Making a brand public needs
        confirm_public: true.
      properties:
        summary:
          type: string
          maxLength: 200
        story:
          type: string
          maxLength: 2000
        size:
          type: string
          enum:
            - ''
            - 1 employee
            - 2-10 employees
            - 11-50 employees
            - 51-200 employees
            - 201-500 employees
            - 501-1000 employees
            - 1001-5000 employees
            - 5001-10,000 employees
            - 10,001+ employees
        company_type:
          type: string
          enum:
            - ''
            - Educational
            - Government Agency
            - Non-Profit
            - Partnership
            - Privately Held
            - Public Company
            - Self-Employed
            - Self-Owned
        year_founded:
          type:
            - string
            - integer
          description: A four digit year, or empty to clear
        url:
          type: string
          description: A public website address, or empty to clear. Same as website
        website:
          type: string
          description: Same as url
        twitter:
          type: string
        facebook:
          type: string
        instagram:
          type: string
        linkedin:
          type: string
        youtube:
          type: string
        github:
          type: string
        social:
          type: object
          additionalProperties: false
          properties:
            twitter:
              type: string
            facebook:
              type: string
            instagram:
              type: string
            linkedin:
              type: string
            youtube:
              type: string
            github:
              type: string
        primary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
        colors:
          type: object
          additionalProperties: false
          description: >-
            primary, secondary and the extra colors. additional replaces the whole extra list (up to
            30); sending only one of secondary or additional keeps the other as it is
          properties:
            primary:
              type: string
              pattern: ^#[0-9a-fA-F]{6}$
            secondary:
              type:
                - string
                - 'null'
              pattern: ^#[0-9a-fA-F]{3,8}$
            additional:
              type: array
              maxItems: 30
              items:
                type: object
                required:
                  - value
                additionalProperties: false
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                    maxLength: 60
                  value:
                    type: string
                    pattern: ^#[0-9a-fA-F]{3,8}$
        print_values:
          type: object
          additionalProperties: true
          description: CMYK and Pantone values per color hex, as GET returns them (up to 40)
        auto_logo_variants:
          type: boolean
          description: Make black and white logo downloads automatically
        fonts:
          type: object
          additionalProperties: false
          description: >-
            headline and body font, each { source: google | adobe, name } or null to clear. A Google
            name must be a Google Fonts family (checked). Adobe also needs css (the family's CSS
            name) and tracking.adobe_kit. A custom font is a file uploaded in the app; the API does
            not set one.
          properties:
            headline:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
            body:
              oneOf:
                - type: 'null'
                - type: object
                  required:
                    - source
                    - name
                  additionalProperties: false
                  properties:
                    source:
                      type: string
                      enum:
                        - google
                        - adobe
                    name:
                      type: string
                      maxLength: 80
                    css:
                      type: string
                      maxLength: 60
        team:
          type: object
          additionalProperties: false
          description: >-
            The people section: a heading (up to 30 characters) and up to 24 members. A photo is
            kept for a member you send again; photo_url sets or replaces it
          properties:
            title:
              type: string
              maxLength: 30
            members:
              type: array
              maxItems: 24
              items:
                type: object
                required:
                  - name
                additionalProperties: false
                properties:
                  id:
                    type: string
                  name:
                    type: string
                    maxLength: 80
                  title:
                    type: string
                    maxLength: 80
                  photo_url:
                    type: string
                    description: A public https image address for the photo; fetched after the text is saved
        press:
          type: array
          maxItems: 24
          items:
            type: object
            required:
              - url
            additionalProperties: false
            properties:
              id:
                type: string
              url:
                type: string
                description: A public page address
              title:
                type: string
                maxLength: 200
              description:
                type: string
                maxLength: 300
              image:
                type: string
                description: A public image address shown with the article
              source:
                type: string
                maxLength: 100
          description: Articles written about the brand
        guidelines:
          type: array
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
              title:
                type: string
                maxLength: 80
              text:
                type: string
                description: 'Plain text: blank line between paragraphs, ''- '' for bullets, ''## '' for a heading'
              images:
                type: array
                maxItems: 12
                description: >-
                  Pictures to add to the section, fetched after the text is saved (an entry without
                  url is ignored, so a read can be sent back)
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    id:
                      type: string
                    url:
                      type: string
                      description: A public https image address
                    kind:
                      type: string
                      enum:
                        - image
                        - do
                        - dont
                    caption:
                      type: string
                      maxLength: 200
          description: >-
            Guideline sections (up to 20). Existing section images stay for a section you send again
            with its id; images adds more
        download_approval:
          type: boolean
        seo:
          type: object
          additionalProperties: false
          properties:
            title:
              type: string
              maxLength: 100
            description:
              type: string
              maxLength: 160
        meta_title:
          type: string
          maxLength: 100
        meta_description:
          type: string
          maxLength: 160
        team_title:
          type: string
          maxLength: 30
        tracking:
          type: object
          properties:
            ga4:
              type: string
            gtm:
              type: string
            search_console:
              type: string
            adobe_kit:
              type: string
          additionalProperties: false
          description: >-
            Google Analytics 4 id (G-...), Tag Manager id (GTM-...), Search Console token and Adobe
            Fonts project. Only the keys sent change
        name:
          type: string
          minLength: 1
          maxLength: 48
        industry:
          type: string
          enum:
            - Arts and Entertainment
            - Business and Consumer Services
            - Community and Society
            - Computer Electronics and Technology
            - E-commerce and Shopping
            - Finance
            - Food and Drink
            - Gambling
            - Games
            - Health
            - Heavy Industry and Engineering
            - Hobbies and Leisure
            - Home and Garden
            - Jobs and Career
            - Law and Government
            - Lifestyle
            - Luxury
            - News and Media
            - Pets and Animals
            - Reference Materials
            - Science and Education
            - Sports
            - Travel and Tourism
            - Vehicles
            - ''
        access:
          type: string
          enum:
            - public
            - restricted
          description: >-
            public also removes the password. restricted needs a contact or organization assigned
            first
        confirm_public:
          type: boolean
          description: >-
            Must be true when access changes to public on a brand that is not public yet; otherwise
            the call is refused (400 confirmation_required)
        is_draft:
          type: boolean
    BrandAssets:
      type: object
      properties:
        brand:
          type: object
          properties:
            id:
              type: string
              format: uuid
            slug:
              type: string
          required:
            - id
            - slug
        images:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - icon
                  - main_logo
                  - banner
              name:
                type: string
              download_url:
                type: string
            required:
              - role
              - name
              - download_url
        logos:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              type:
                type:
                  - string
                  - 'null'
              download_url:
                type: string
            required:
              - id
              - name
              - type
              - download_url
        collections:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              description:
                type: string
              files:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string
                    type:
                      type:
                        - string
                        - 'null'
                    size:
                      type:
                        - string
                        - 'null'
                    download_url:
                      type: string
                  required:
                    - id
                    - name
                    - type
                    - size
                    - download_url
            required:
              - id
              - name
              - description
              - files
        links_expire:
          type: boolean
          description: 'Always true: the download links are short-lived; list again for fresh ones'
      required:
        - brand
        - images
        - logos
        - collections
        - links_expire
    Series:
      type: array
      items:
        type: object
        properties:
          date:
            type: string
          count:
            type: integer
        required:
          - date
    BrandAnalytics:
      type: object
      properties:
        period:
          type: string
          enum:
            - 30d
            - 90d
            - all
        views:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        downloads:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        requests:
          type: object
          properties:
            total:
              type: integer
            series:
              $ref: '#/components/schemas/Series'
          required:
            - total
            - series
        downloaded_files:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                top_assets:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                    required:
                      - name
                      - count
                formats:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                    required:
                      - name
                      - count
                unrecorded:
                  type: integer
              required:
                - top_assets
                - formats
                - unrecorded
          description: >-
            The most downloaded files and the formats taken in the period; null until the file
            columns exist. Downloads from before files were recorded are counted in `unrecorded`.
      required:
        - period
        - views
        - downloads
        - requests
        - downloaded_files
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
        description:
          type:
            - string
            - 'null'
        events:
          type: array
          items:
            type: string
          description: The event types this endpoint receives, or ["*"] for every event
        enabled:
          type: boolean
        disabled_reason:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
          description: >-
            Why the endpoint is off: turned_off, no_success_for_5_days, deliveries_kept_failing or
            endpoint_gone
        disabled_at:
          type:
            - string
            - 'null'
          format: date-time
        last_success_at:
          type:
            - string
            - 'null'
          format: date-time
        last_failure_at:
          type:
            - string
            - 'null'
          format: date-time
        failed_attempts_in_a_row:
          type: integer
        secret_rotation_ends_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 'While a rotated secret is still signing alongside the new one: when it stops'
        created_at:
          type: string
          format: date-time
      required:
        - id
        - url
        - description
        - events
        - enabled
        - disabled_reason
        - disabled_at
        - last_success_at
        - last_failure_at
        - failed_attempts_in_a_row
        - secret_rotation_ends_at
        - created_at
    WebhookEndpointList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - data
    WebhookEndpointCreate:
      type: object
      properties:
        url:
          type: string
          description: >-
            https only, a public name (no IP number, localhost or internal name), port 443 or 1024
            and up, at most 2000 characters
        events:
          type: array
          items:
            type: string
          description: Event types to receive; omit for every event
        description:
          type:
            - string
            - 'null'
          maxLength: 200
      required:
        - url
    WebhookEndpointUpdate:
      type: object
      description: At least one field.
      properties:
        url:
          type: string
        events:
          type: array
          items:
            type: string
        description:
          type:
            - string
            - 'null'
          maxLength: 200
        enabled:
          type: boolean
          description: false stops deliveries; true starts them again and clears the failure count
    WebhookEndpointCreated:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
        secret:
          type: string
          description: The signing secret (whsec_...). It is shown only now
      required:
        - endpoint
        - secret
    WebhookSecretRotated:
      type: object
      properties:
        secret:
          type: string
          description: The new signing secret. It is shown only now
        previous_secret_expires_at:
          type: string
          format: date-time
          description: The old secret also signs until then
      required:
        - secret
        - previous_secret_expires_at
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
        event_id:
          type: string
          description: The id inside the event body; the same on every retry, so a receiver can ignore a repeat
        event_type:
          type: string
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          description: 'pending: waiting for a try; failed: every try was used'
        attempts:
          type: integer
        next_attempt_at:
          type:
            - string
            - 'null'
          format: date-time
        response_status:
          type:
            - integer
            - 'null'
        error:
          type:
            - string
            - 'null'
        response_body:
          type:
            - string
            - 'null'
          description: The start of the receiver's answer
        attempt_log:
          type: array
          items:
            type: object
            properties:
              at:
                type: string
                format: date-time
              status:
                type:
                  - integer
                  - 'null'
              error:
                type:
                  - string
                  - 'null'
              ms:
                type:
                  - integer
                  - 'null'
            required:
              - at
              - status
              - error
              - ms
        created_at:
          type: string
          format: date-time
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - event_id
        - event_type
        - status
        - attempts
        - next_attempt_at
        - response_status
        - error
        - response_body
        - attempt_log
        - created_at
        - delivered_at
    WebhookDeliveryList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDelivery'
      required:
        - data
    WebhookDeleted:
      type: object
      properties:
        deleted:
          type: boolean
      required:
        - deleted
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          description: evt_..., stable across retries
        type:
          type: string
          description: For example webhook.test
        api_version:
          type: string
          enum:
            - v1
        created_at:
          type: string
          format: date-time
        workspace_key:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
        - id
        - type
        - api_version
        - created_at
        - workspace_key
        - data
    AccessRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - download
            - view
        name:
          type: string
        company:
          type:
            - string
            - 'null'
        email:
          type: string
        message:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - approved
            - rejected
        created_at:
          type: string
          format: date-time
        decided_at:
          oneOf:
            - type: 'null'
            - type: string
              format: date-time
      required:
        - id
        - kind
        - name
        - company
        - email
        - message
        - status
        - created_at
        - decided_at
    RequestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AccessRequest'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - data
        - next_cursor
    Decision:
      type: object
      properties:
        action:
          type: string
          enum:
            - approve
            - reject
      required:
        - action
    DecisionResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - approved
            - rejected
        emailed:
          type: boolean
      required:
        - id
        - status
    Entry:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: >-
            The absolute path. Present on single-item reads, on writes and in a recursive listing;
            absent from a plain folder listing
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
    EntryWithPath:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: The absolute path, such as /photos/2026/a.jpg
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
        - path
    FileList:
      type: object
      properties:
        folder:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: The folder that was listed; null for the library root
          required:
            - id
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as ?cursor= for the next page; null on the last page. Opaque: do not build or parse
            it.
      required:
        - folder
        - entries
        - next_cursor
    FileSearch:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              file_id:
                type: integer
              name:
                type: string
              folder_id:
                type:
                  - string
                  - 'null'
                format: uuid
              page:
                type:
                  - integer
                  - 'null'
              snippet:
                type: string
            required:
              - file_id
              - name
              - folder_id
              - page
              - snippet
        coverage:
          type: object
          properties:
            files:
              type: integer
            searched:
              type: integer
            notSearchable:
              type: integer
            waiting:
              type: integer
            partial:
              type: integer
              description: 'Searched files too long to index completely: only their first part is searchable'
          required:
            - files
            - searched
            - notSearchable
            - waiting
            - partial
      required:
        - results
        - coverage
    AskRequest:
      type: object
      properties:
        question:
          type: string
          minLength: 1
          maxLength: 4000
          description: >-
            What to ask about the files. Each call is a separate question: nothing from an earlier
            call is remembered.
        folder:
          type: string
          format: uuid
          description: Only answer from this folder and its subfolders
        mode:
          type: string
          enum:
            - basic
            - deep
          default: basic
          description: deep is slower and thorough; Pro plans and organizations with their own AI key only
        history:
          type: array
          maxItems: 20
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - assistant
              content:
                type: string
                minLength: 1
                maxLength: 8000
            required:
              - role
              - content
          description: >-
            Earlier questions and answers of this conversation, oldest first, so a follow-up makes
            sense; each is charged as input
      required:
        - question
    AskAnswer:
      type: object
      properties:
        answer:
          type: string
          description: The answer; the files it used are cited as [1], [2]
        sources:
          type: array
          items:
            type: object
            properties:
              'n':
                type: integer
              file_id:
                type:
                  - integer
                  - 'null'
              name:
                type: string
              pages:
                type: array
                items:
                  type: integer
            required:
              - 'n'
              - file_id
              - name
              - pages
        credits_used:
          type: number
          description: AI credits this question used
        paid_by:
          type:
            - string
            - 'null'
          description: plan, extra or key
        mode:
          type: string
          enum:
            - basic
            - deep
        notes:
          type: array
          items:
            type: string
          description: >-
            Estimates made before a big read, e.g. "Looked at pages: about 160 credits" (from the
            file size); credits_used is the real total. Empty for most questions
      required:
        - answer
        - sources
        - credits_used
        - paid_by
        - mode
        - notes
    FileText:
      type: object
      properties:
        file_id:
          type: integer
        name:
          type: string
        text:
          type: string
        from_page:
          type:
            - integer
            - 'null'
        to_page:
          type:
            - integer
            - 'null'
        truncated:
          type: boolean
      required:
        - file_id
        - name
        - text
        - from_page
        - to_page
        - truncated
    FileDownload:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        size:
          type: integer
          minimum: 0
          description: Bytes
        download_url:
          type: string
          format: uri
          description: A signed URL; no token needed to fetch it
        expires_in:
          type: integer
          description: Seconds the URL keeps working (900)
        links_expire:
          type: boolean
          description: 'Always true: ask again for a fresh link'
      required:
        - id
        - name
        - size
        - download_url
        - expires_in
        - links_expire
    FolderCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: The folder name, at most 255 bytes
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder to create it in. Omit or null for the library root
        visibility:
          type: string
          enum:
            - private
            - workspace
          description: >-
            private (the default): its creator, whoever it is shared with, owners and admins.
            workspace: every member of the workspace can see it
      required:
        - name
    FilePatch:
      type: object
      minProperties: 1
      description: Send at least one key. Other keys, such as a path or a parent name, are refused.
      properties:
        name:
          type: string
          minLength: 1
          description: The new name, at most 255 bytes
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Move into this folder; null moves to the library root
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead. Files only
        visibility:
          type: string
          enum:
            - private
            - workspace
          description: >-
            Folders only: who can see it. Only the person who made the folder, an owner or an admin
            can change it
    PdfEditRequest:
      type: object
      description: At least one tool. Page numbers start at 1. camelCase names are accepted too.
      properties:
        merge_file_ids:
          type: array
          items:
            type: string
          description: Ids of other PDFs (digits) to append, in order; up to 9
        keep:
          type: string
          description: Keep only these pages, like 1-3,5,8-
        remove:
          type: string
          description: Remove these pages. Use keep or remove, not both
        order:
          type: array
          items:
            type: integer
          description: A new page order, like [3, 1, 2]
        rotate:
          type: array
          items:
            type: object
            properties:
              pages:
                type: string
              degrees:
                type: integer
                enum:
                  - 90
                  - 180
                  - 270
            required:
              - degrees
          description: Rotate pages clockwise
        crop:
          type: object
          properties:
            top:
              type: number
            right:
              type: number
            bottom:
              type: number
            left:
              type: number
            pages:
              type: string
          required: []
        blank_after:
          type: string
          description: Add a blank page after these pages
        blank_at_start:
          type: boolean
        page_numbers:
          oneOf:
            - type: boolean
            - type: object
              properties:
                position:
                  type: string
                  enum:
                    - bottom-center
                    - bottom-right
                    - bottom-left
                    - top-center
                    - top-right
                    - top-left
                start:
                  type: integer
              required: []
        watermark:
          type: string
          description: Text drawn over every page (hides nothing underneath)
        title:
          type: string
        author:
          type: string
        name:
          type: string
          description: The new file's name (the .pdf extension is added or corrected)
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The folder for the new file; null for the library root; omitted keeps the source's
            folder
    ConvertRequest:
      type: object
      required:
        - to
      properties:
        to:
          type: string
          enum:
            - text
            - images
            - split
            - word
            - excel
            - pdf
            - ocr
            - redact
            - compress
            - protect
            - unlock
        pages:
          type: string
          description: 'For text, images, word, excel, ocr and redact: only these pages, like 1-5'
        image_format:
          type: string
          enum:
            - png
            - jpg
          description: For images (default png)
        ranges:
          type: string
          description: 'For split: ''each'' (default) or groups like 1-3,4-6'
        more_file_ids:
          type: array
          items:
            type: string
          description: 'For pdf from pictures: the other pictures'' ids in order (the source is the first)'
        page_size:
          type: string
          enum:
            - fit
            - a4
            - letter
          description: For pdf from pictures (default fit)
        terms:
          type: array
          items:
            type: string
          description: >-
            For redact: the exact texts to black out (2 to 100 characters each, up to 50; case does
            not matter)
        emails:
          type: boolean
          description: 'For redact: black out every email address'
        level:
          type: string
          enum:
            - light
            - medium
            - strong
          description: For compress (default medium)
        password:
          type: string
          description: >-
            For protect (4 to 100 characters) and unlock (the PDF's current password). Used for this
            call only; never stored or logged
        name:
          type: string
          description: The new file's name (the right extension is added or corrected)
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The folder for the new file; null for the library root; omitted keeps the source's
            folder
    DocumentCreate:
      type: object
      required:
        - name
        - format
      properties:
        name:
          type: string
          description: The file's name; the extension is added or corrected
        format:
          type: string
          enum:
            - pdf
            - docx
            - pptx
            - md
            - xlsx
            - csv
        markdown:
          type: string
          description: >-
            For pdf, docx, pptx and md: the content in Markdown, up to 60,000 characters (at least
            20)
        table:
          type: object
          description: 'For xlsx and csv: up to 12 columns and 500 rows of text'
          properties:
            columns:
              type: array
              items:
                type: string
              minItems: 1
              maxItems: 12
            rows:
              type: array
              items:
                type: array
                items:
                  type: string
              minItems: 1
              maxItems: 500
          required:
            - columns
            - rows
        sources:
          type: array
          items:
            type: string
          description: File ids (digits) the document is based on, up to 10; a Sources list is added
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; null or omitted for the library root
    TemplateFill:
      type: object
      required:
        - values
      properties:
        values:
          type: object
          description: >-
            Each placeholder name (exactly as written in the template) to text, or to a list of rows
            for a repeated block
          additionalProperties: true
        name:
          type: string
          description: The new file's name; default '<template> (filled).docx'
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; omitted keeps the template's folder
    OfficeEdit:
      type: object
      description: >-
        Send the fields of the file's kind: .docx edits, inserts, track_changes; .pptx edits; .xlsx
        cells, append_rows. camelCase names are accepted too.
      properties:
        edits:
          type: array
          items:
            type: object
            properties:
              find:
                type: string
              replace:
                type: string
            required:
              - find
              - replace
          description: Exact text to find and its replacement (empty deletes), up to 50 for Word and PowerPoint
        inserts:
          type: array
          items:
            type: object
            description: >-
              One of: paragraphs (a list of text), table ({ columns, rows }), image ({ file_id,
              width_inches? }); after: some text of the paragraph to insert after (omitted: at the
              end)
            properties:
              after:
                type: string
              paragraphs:
                type: array
                items:
                  type: string
              table:
                type: object
              image:
                type: object
          description: Word only
        track_changes:
          type: boolean
          description: 'Word only: record the changes as tracked changes by Tarkle'
        cells:
          type: array
          items:
            type: object
            properties:
              sheet:
                type: string
              cell:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: number
            required:
              - sheet
              - cell
              - value
          description: Excel only, up to 100; an empty value clears the cell
        append_rows:
          type: array
          items:
            type: object
            properties:
              sheet:
                type: string
              rows:
                type: array
                items:
                  type: array
                  items:
                    oneOf:
                      - type: string
                      - type: number
            required:
              - sheet
              - rows
          description: Excel only, up to 200 rows in all
        name:
          type: string
          description: The new file's name; default '<name> (edited).<ext>'
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder; omitted keeps the source's folder
    FileToolResult:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/EntryWithPath'
        notes:
          type: array
          items:
            type: string
          description: What was done, in plain words
      required:
        - file
        - notes
    FileCopy:
      type: object
      description: Both keys are optional.
      properties:
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The destination folder; null for the library root; omitted keeps the original's folder
        name:
          type: string
          minLength: 1
          description: The new name, at most 255 bytes; omitted keeps the original's name
    DeleteResult:
      type: object
      properties:
        deleted:
          type: boolean
          description: Always true
        deleted_transfers:
          type: array
          items:
            type: integer
          description: >-
            The ids of the transfers deleted with the item (empty unless confirm_delete_transfers
            was true)
      required:
        - deleted
        - deleted_transfers
    Usage:
      type: object
      properties:
        storage:
          type: object
          properties:
            used_bytes:
              type: integer
              minimum: 0
            limit_bytes:
              type:
                - integer
                - 'null'
              minimum: 0
              description: The plan's limit; null when there is none
            free_bytes:
              type:
                - integer
                - 'null'
              minimum: 0
              description: limit_bytes minus used_bytes; null when there is no limit
          required:
            - used_bytes
            - limit_bytes
            - free_bytes
      required:
        - storage
    WorkspaceRef:
      type: object
      properties:
        workspace_key:
          type:
            - string
            - 'null'
          description: Send as X-Workspace-Key
        name:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        relationship:
          type: string
          enum:
            - owner
            - member
            - linked
      required:
        - workspace_key
        - name
        - url
        - relationship
    WorkspaceList:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceRef'
      required:
        - workspaces
    UploadStart:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: The file name, at most 255 bytes
        size:
          type: integer
          minimum: 0
          description: The file's size in bytes. 0 creates an empty file at once
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: The folder to upload into. Omit or null for the library root
        content_type:
          type: string
          maxLength: 100
          description: The media type, without control characters. Default application/octet-stream
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: The SHA-256 of the file's bytes as 64 hexadecimal characters
        on_conflict:
          type: string
          enum:
            - version
            - separate
            - skip
          description: >-
            Your answer when the app's duplicate rule would ask: version, separate or skip. See
            startUpload
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead
      required:
        - name
        - size
    UploadPart:
      type: object
      properties:
        partNumber:
          type: integer
          minimum: 1
        url:
          type: string
          format: uri
          description: 'A signed URL: PUT that part''s bytes to it'
      required:
        - partNumber
        - url
    UploadStarted:
      type: object
      properties:
        action:
          type: string
          enum:
            - upload
        will_be_renamed:
          type: boolean
          description: True when the name was taken and the file will get a numbered name
        folder_id:
          type:
            - string
            - 'null'
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending, uploading, completed, failed, aborted or expired
        name:
          type: string
        size:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
          description: Bytes per part (the last part can be smaller)
        part_count:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        content_type:
          type: string
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
          description: 'Signed URLs: one for a single upload, the first batch of parts for a multipart upload'
      required:
        - action
        - will_be_renamed
        - folder_id
        - id
        - status
        - name
        - size
        - mode
        - part_size
        - part_count
        - expires_at
        - content_type
        - uploads
    UploadStartedVersion:
      type: object
      properties:
        action:
          type: string
          enum:
            - upload
        kind:
          type: string
          enum:
            - version
          description: This upload adds a new version to an existing file
        will_be_renamed:
          type: boolean
          description: Always false for a version
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending
        name:
          type: string
        size:
          type: integer
          minimum: 0
        file_id:
          type: string
          description: The existing file this version belongs to
        folder_id:
          type:
            - string
            - 'null'
        retention_days:
          type:
            - integer
            - 'null'
          description: How long older versions are kept; null when there is no limit
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        multipart_id:
          type: string
          description: 'Multipart uploads only: send it back where an endpoint asks for multipart_id'
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
          description: 'Signed URLs: one for a single upload, the first batch of parts for a multipart upload'
      required:
        - action
        - kind
        - will_be_renamed
        - id
        - status
        - name
        - size
        - file_id
        - folder_id
        - retention_days
        - mode
        - part_size
        - part_count
        - uploads
    FileCreated:
      type: object
      properties:
        action:
          type: string
          enum:
            - created
        kind:
          type: string
          enum:
            - empty
        file:
          oneOf:
            - $ref: '#/components/schemas/EntryWithPath'
            - type: 'null'
          description: The empty file that was created
      required:
        - action
        - kind
        - file
    UploadSkipped:
      type: object
      properties:
        action:
          type: string
          enum:
            - skip
        existing:
          oneOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
            - type: 'null'
          description: The identical file that is already there
      required:
        - action
        - existing
    UploadStatus:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: pending, uploading, completed, failed, aborted or expired
        name:
          type: string
        size:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        expires_at:
          type: string
          format: date-time
        parts_received:
          type: integer
          minimum: 0
          description: 'Multipart uploads: how many parts have arrived'
        file:
          oneOf:
            - $ref: '#/components/schemas/EntryWithPath'
            - type: 'null'
          description: The finished file, once the upload is completed
      required:
        - id
        - status
        - name
        - size
        - mode
        - part_size
        - part_count
        - expires_at
    UploadStatusVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - version
        status:
          type: string
          enum:
            - completed
            - pending
            - expired
        size:
          type: integer
          minimum: 0
        file_id:
          type: string
        mode:
          type: string
          enum:
            - single
            - multipart
          description: 'single: one signed URL; multipart: signed part URLs of part_size bytes each'
        part_size:
          type: integer
          minimum: 1
        part_count:
          type: integer
          minimum: 1
        parts_received:
          type: integer
          minimum: 0
          description: 'Multipart uploads: how many parts have arrived'
      required:
        - id
        - kind
        - status
        - size
        - file_id
        - mode
        - part_size
        - part_count
    UploadAborted:
      type: object
      properties:
        aborted:
          type: boolean
          description: Always true
      required:
        - aborted
    UploadPartsRequest:
      type: object
      description: All keys are optional.
      properties:
        from_part:
          type: integer
          minimum: 1
          default: 1
          description: The first part number to sign; at most part_count
        count:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: How many parts to sign
        multipart_id:
          type: string
          maxLength: 1023
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
    UploadParts:
      type: object
      properties:
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/UploadPart'
      required:
        - uploads
    UploadCompleteRequest:
      type: object
      description: All keys are optional; an empty body is fine.
      properties:
        multipart_id:
          type: string
          maxLength: 1023
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: The SHA-256 of the file's bytes as 64 hexadecimal characters
        modified_at:
          type: string
          format: date-time
          description: >-
            The file's own modification time: ISO 8601 with a time zone, after 1970-01-02 and at
            most one day ahead
    UploadCompleted:
      type: object
      properties:
        id:
          type: string
          description: A file id is digits, a folder id is a uuid
        type:
          type: string
          enum:
            - file
            - folder
        name:
          type: string
        size:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Bytes. null for a folder
        category:
          type:
            - string
            - 'null'
          description: >-
            The file type the app tags it with, for example image, video or document. null for a
            folder
        parent_id:
          type:
            - string
            - 'null'
          description: The id of the folder it sits in. null in the library root
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The file's own modification time when the uploader set one, else updated_at
        sha256:
          type:
            - string
            - 'null'
          description: SHA-256 of the bytes as lowercase hex, when known. null for a folder
        sha256_source:
          type:
            - string
            - 'null'
          enum:
            - server
            - client
            - null
          description: 'server: we verified it; client: the uploader''s unverified claim'
        etag:
          type:
            - string
            - 'null'
          description: A marker that changes when the file changes. null for a folder
        protected:
          type: boolean
          description: >-
            True when a protection rule applies to the item; protection_kind says which. Some writes
            on protected items are refused
        protection_kind:
          type:
            - string
            - 'null'
          enum:
            - system
            - request
            - team
            - transfer
            - null
        visibility:
          type:
            - string
            - 'null'
          enum:
            - private
            - workspace
            - null
          description: >-
            A folder is private (its creator, whoever it was shared with, owners and admins) or
            workspace (every member sees it). null for a file
        path:
          type: string
          description: The absolute path, such as /photos/2026/a.jpg
        version_created:
          type: boolean
          description: >-
            Version uploads only: false when the bytes were identical to the current version, so
            nothing was added
      required:
        - id
        - type
        - name
        - size
        - category
        - parent_id
        - created_at
        - updated_at
        - modified_at
        - sha256
        - sha256_source
        - etag
        - protected
        - protection_kind
        - visibility
        - path
    TransferItem:
      type: object
      properties:
        id:
          type: string
          description: >-
            A file id (digits) or a folder id (uuid), already in the library (upload it first with
            POST /uploads)
        type:
          type: string
          enum:
            - file
            - folder
      required:
        - id
        - type
    TransferCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - standard
            - video
            - audio
            - canvas
          default: standard
          description: >-
            standard: a plain file/folder link (the rest of this schema). video/audio: a single
            already-uploaded file of that type, wrapped in a media player. canvas: one or more
            PDF/image files as a feedback board -- see TransferCreateRich for those three
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransferItem'
          minItems: 1
          description: 'At least one existing file or folder from the library (type: standard only)'
        access:
          type: string
          enum:
            - public
            - password
          description: 'public: anyone with the link; password: also needs the password'
        password:
          type: string
          minLength: 1
          description: Required when access is "password"
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the link stops working. Must be in the future. Omit or null for a link that never
            expires
        burn_after_read:
          type: boolean
          description: The link stops working after its first download
        view_only:
          type: boolean
        download_mode:
          type: string
          enum:
            - standard
            - email_required
            - direct
          default: standard
        feedback_deadline_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            type: canvas only. When board comments close. Must be in the future. Omit or null to
            never close
      required:
        - items
        - access
    Transfer:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          description: The public share link
        type:
          type: string
          enum:
            - standard
            - video
            - audio
            - canvas
          description: >-
            video/audio/canvas transfers only answer id, url and type -- see TransferCreate's type
            field
        slug:
          type: string
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        access:
          type: string
          enum:
            - public
            - password
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        burn_after_read:
          type: boolean
        view_only:
          type: boolean
        download_mode:
          type: string
          enum:
            - standard
            - email_required
            - direct
        created_at:
          type: string
          format: date-time
      required:
        - id
        - url
    TransferDeleted:
      type: object
      properties:
        deleted:
          type: boolean
        id:
          type: string
      required:
        - deleted
        - id
    GalleryCreate:
      type: object
      properties:
        folder_id:
          type: string
          format: uuid
          description: A folder whose JPG, PNG and WebP files (directly in it, up to 500) become the gallery
        title:
          type: string
          minLength: 1
          maxLength: 120
        price:
          type: string
          pattern: ^\d{1,5}(\.\d{1,2})?$
          description: 0.01 to 99999.99 in the currency's main unit. Omit for a free gallery
        currency:
          type: string
          enum:
            - USD
            - EUR
            - GBP
            - CAD
            - AUD
            - CHF
            - SEK
            - NOK
            - DKK
            - PLN
            - CZK
            - NZD
            - SGD
            - HKD
            - MXN
          default: USD
          description: The buyer always pays in this currency
        preview_mode:
          type: string
          enum:
            - all
            - first
          default: all
          description: >-
            Paid only. all: every photo as a watermarked preview; first: only the first
            preview_count, the rest blurred
        preview_count:
          type: integer
          minimum: 0
          maximum: 6
          default: 3
        watermark:
          type: boolean
          description: Free galleries only (a paid gallery is always watermarked until bought)
        client_name:
          type: string
          maxLength: 120
          description: Shown on the gallery as "For <name>"
        client_email:
          type: string
          format: email
          description: Kept for your own use; Tarkle does not email it
      required:
        - folder_id
        - title
    GalleryPurchase:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - completed
            - refunded
          description: Only completed means the buyer paid
        amount:
          type: string
        currency:
          type: string
        buyer_name:
          type:
            - string
            - 'null'
        buyer_email:
          type:
            - string
            - 'null'
        paid_at:
          type: string
          format: date-time
        access_until:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - status
        - amount
        - currency
        - buyer_name
        - buyer_email
        - paid_at
        - access_until
    Gallery:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        title:
          type:
            - string
            - 'null'
        paid:
          type: boolean
        price:
          type:
            - string
            - 'null'
          description: '"600.00", or null for a free gallery'
        currency:
          type:
            - string
            - 'null'
        watermark:
          type: boolean
        preview_mode:
          type:
            - string
            - 'null'
          enum:
            - all
            - first
            - null
        preview_count:
          type:
            - integer
            - 'null'
        photo_count:
          type: integer
        gallery_url:
          type: string
          format: uri
          description: '/g/...: the gallery, with a Buy button when paid'
        pay_url:
          type:
            - string
            - 'null'
          format: uri
          description: '/pay/...: the checkout of a paid gallery, to send to the buyer; null when free'
        disabled:
          type: boolean
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        purchases:
          type: array
          items:
            $ref: '#/components/schemas/GalleryPurchase'
      required:
        - id
        - slug
        - title
        - paid
        - price
        - currency
        - watermark
        - preview_mode
        - preview_count
        - photo_count
        - gallery_url
        - pay_url
        - disabled
        - created_at
    ContactCreate:
      type: object
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        organization_name:
          type: string
        business:
          type: boolean
      required:
        - email
    ContactOrganization:
      type: object
      properties:
        organizationId:
          type: string
        name:
          type: string
      required:
        - organizationId
        - name
    Contact:
      type: object
      properties:
        contactId:
          type: string
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
        portalAccess:
          type: boolean
        portalInvitedAt:
          type:
            - string
            - 'null'
          format: date-time
        portalSignedIn:
          type: boolean
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/ContactOrganization'
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - contactId
        - name
        - email
        - status
        - portalAccess
        - portalInvitedAt
        - portalSignedIn
        - organizations
        - createdAt
    ContactList:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
      required:
        - contacts
    ContactPortalAccessSet:
      type: object
      properties:
        enabled:
          type: boolean
      required:
        - enabled
    ContactPortalAccess:
      type: object
      properties:
        contactId:
          type: string
        portalAccess:
          type: boolean
        inviteEmailSent:
          type: boolean
      required:
        - contactId
        - portalAccess
        - inviteEmailSent
    ContactPortalInvite:
      type: object
      properties:
        contactId:
          type: string
        inviteEmailSent:
          type: boolean
      required:
        - contactId
        - inviteEmailSent
    ContactStorageLimitSet:
      type: object
      properties:
        limit_gb:
          type: number
          minimum: 1
          maximum: 10000
          description: How much the contact may upload from their portal, in GB
      required:
        - limit_gb
    ContactStorageLimitChanged:
      type: object
      properties:
        contactId:
          type: string
        limitBytes:
          type: integer
      required:
        - contactId
        - limitBytes
    ContactStorageLimit:
      type: object
      properties:
        contactId:
          type: string
        limitBytes:
          type: integer
        usedBytes:
          type: integer
          description: What the contact has uploaded from their portal so far
      required:
        - contactId
        - limitBytes
        - usedBytes
    TransferUpdate:
      type: object
      properties:
        view_only:
          type: boolean
          description: >-
            false: the people the transfer was delivered to can download its files. true: they can
            only view them
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: A future date at most three years ahead, or null to remove the expiry
        password:
          type:
            - string
            - 'null'
          minLength: 4
          maxLength: 100
          description: 4 to 100 characters, or null to remove the password. Never returned
      required: []
    TransferContactsAdd:
      type: object
      properties:
        contact_ids:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          maxItems: 50
          description: Contact ids from createContact's or listContacts' answer
      required:
        - contact_ids
    TransferContacts:
      type: object
      properties:
        id:
          type: string
        contact_ids:
          type: array
          items:
            type: string
          description: Every contact the transfer is delivered to
        added:
          type: array
          items:
            type: string
          description: The ids this call added (empty when they were all there already)
        view_only:
          type: boolean
      required:
        - id
        - contact_ids
        - added
        - view_only
    FileRequestCreate:
      type: object
      properties:
        title:
          type: string
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        destination_folder:
          type:
            - string
            - 'null'
        is_public:
          type: boolean
          default: true
        email_notifications:
          type: boolean
          default: false
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Must be in the future. Omit or null for a request that never expires
      required:
        - title
    FileRequest:
      type: object
      properties:
        id:
          type: string
        shortId:
          type:
            - string
            - 'null'
        url:
          type: string
          format: uri
          description: The public upload link
        title:
          type: string
        description:
          type:
            - string
            - 'null'
        destinationFolder:
          type:
            - string
            - 'null'
        isPublic:
          type: boolean
        completed:
          type: boolean
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - shortId
        - url
        - title
        - description
        - destinationFolder
        - isPublic
        - completed
        - expiresAt
        - createdAt
    FileRequestList:
      type: object
      properties:
        fileRequests:
          type: array
          items:
            $ref: '#/components/schemas/FileRequest'
      required:
        - fileRequests
    TeamCreate:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        description:
          type: string
          maxLength: 120
        access:
          type: string
          enum:
            - everyone
            - members
          default: everyone
          description: >-
            everyone: every workspace member sees it. members: only members added later, through the
            app
        budget_gb:
          type: number
          minimum: 1
          maximum: 1000000
          description: A fixed storage budget in GB. Omit or null for no limit
      required:
        - name
    Team:
      type: object
      properties:
        id:
          type: string
        masterFolderId:
          type:
            - string
            - 'null'
        name:
          type: string
        access:
          type: string
          enum:
            - everyone
            - members
      required:
        - id
        - masterFolderId
        - name
        - access
    TeamListItem:
      type: object
      properties:
        id:
          type: string
        masterFolderId:
          type:
            - string
            - 'null'
        name:
          type: string
        description:
          type: string
        access:
          type: string
          enum:
            - everyone
            - members
        created_at:
          type: string
          format: date-time
      required:
        - id
        - masterFolderId
        - name
        - description
        - access
        - created_at
    TeamList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TeamListItem'
      required:
        - data
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Makes a write safe to repeat. Send a random value (a UUID is fine) of up to 255 visible
        characters. A repeat of the same request gets the first answer again, with the header
        `Idempotent-Replayed: true`, and does nothing twice. The same key for a different request is
        422 `idempotency_key_reused`; the same request while the first one is still running is 409
        `idempotency_in_progress`. A 5xx or 429 is not remembered, so retrying it runs the request
        again. Keys last 24 hours and belong to the account that created the token.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  headers:
    RateLimitLimit:
      description: >-
        Requests allowed per minute for this API key (the plan's number: Free 50, Pro 250, Agency
        500
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current minute
      schema:
        type: integer
    RateLimitReset:
      description: When the current window ends, in Unix seconds
      schema:
        type: integer
    IetfRateLimitLimit:
      description: The same limit in the IETF RateLimit header form (draft-ietf-httpapi-ratelimit-headers)
      schema:
        type: integer
    IetfRateLimitRemaining:
      description: Requests left in the current minute
      schema:
        type: integer
    IetfRateLimitReset:
      description: Seconds until the current window ends (X-RateLimit-Reset is the same moment as Unix seconds)
      schema:
        type: integer
    IetfRateLimitPolicy:
      description: >-
        The policies, for example 250;w=60, 25000;w=86400: 250 requests per 60-second window and
        25,000 per day for the organization
      schema:
        type: string
    Deprecation:
      description: >-
        Sent ONLY on a deprecated version or endpoint (none today): RFC 9745 structured date,
        "@<unix seconds>", when it was deprecated
      schema:
        type: string
    Sunset:
      description: >-
        Sent ONLY on a deprecated version or endpoint (none today): RFC 8594 HTTP-date after which
        it may stop working
      schema:
        type: string
    DeprecationLink:
      description: >-
        Sent ONLY with Deprecation: links with rel=deprecation (the policy), rel=sunset and
        rel=successor-version
      schema:
        type: string
    QuotaLimit:
      description: >-
        The organization's daily API quota (requests a day, shared by all its API keys and
        workspaces; resets at midnight UTC)
      schema:
        type: integer
    QuotaRemaining:
      description: Daily quota units left today (a search costs 5, everything else 1)
      schema:
        type: integer
    QuotaReset:
      description: When the daily quota resets (the next midnight UTC), in Unix seconds
      schema:
        type: integer
    QuotaWarning:
      description: 'Sent from 80% of the daily quota until it resets: the value is 80%'
      schema:
        type: string
    RateLimitHeavyLimit:
      description: >-
        Sent on search and AI requests: how many of them this key may make a minute (they also count
        in X-RateLimit-Limit and the daily quota)
      schema:
        type: integer
    RateLimitHeavyRemaining:
      description: 'Sent on search and AI requests: how many are left this minute'
      schema:
        type: integer
    RetryAfter:
      description: >-
        Seconds to wait before trying again: the end of the minute for rate_limited, midnight UTC
        for quota_exceeded
      schema:
        type: integer
    ApiVersion:
      description: The API version that answered
      schema:
        type: string
    WwwAuthenticate:
      description: Bearer with a resource_metadata URL (RFC 9728), on every 401
      schema:
        type: string
  responses:
    BadRequest:
      description: >-
        The request is invalid: a parameter, the body or the workspace key is wrong
        (invalid_request, invalid_name, workspace_required, confirmation_required and others). code
        says which
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: >-
        The token is missing, invalid or revoked (unauthorized), or it is an older workspace-bound
        token (legacy_token). Create a token in Settings > API. The rate-limit headers describe the
        caller's IP bucket here, since no token was identified
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticate'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: >-
        The token lacks the scope this operation needs (see x-required-scope) or has no scopes
        (token_without_scopes), has no access to the workspace (no_access), its creator may not do
        this (forbidden), or the item is protected (protected)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: The brand, request, file, folder or upload does not exist in this workspace (not_found)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: >-
        The request conflicts with the current state, for example a taken name (name_taken), a
        request that is already decided, an item a transfer holds (transfer_active), or missing
        upload parts (incomplete); or, on a write, a request with the same Idempotency-Key is still
        running (idempotency_in_progress). code says which
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Gone:
      description: 'Gone for good: the upload expired or failed (expired, failed)'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PayloadTooLarge:
      description: >-
        Over the plan's storage or file-size limit, or too large to list (storage_full,
        file_too_large, storage_limit_exceeded, too_large)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unprocessable:
      description: >-
        The bytes do not match what was announced (integrity_mismatch, size_mismatch), or the
        Idempotency-Key was already used for a different request (idempotency_key_reused)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: >-
        Too many requests (rate_limited): the key's per-minute limit, or its search and AI limit,
        was hit; wait Retry-After seconds. The organization's daily quota is used up
        (quota_exceeded): Retry-After is the seconds until midnight UTC, and a refused request costs
        no quota. Too many unfinished uploads is too_many_uploads
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServerError:
      description: Something went wrong on our side (server_error). Try again later
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadGateway:
      description: Cloud storage did not answer (storage_unavailable). Try again
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unavailable:
      description: >-
        Temporarily unavailable: the files API is switched off, the plan or storage could not be
        read, or an Idempotency-Key could not be recorded so the write was not run (unavailable,
        entitlement_unresolved). Try again later
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Limit:
          $ref: '#/components/headers/IetfRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/IetfRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/IetfRateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/IetfRateLimitPolicy'
        X-RateLimit-Heavy-Limit:
          $ref: '#/components/headers/RateLimitHeavyLimit'
        X-RateLimit-Heavy-Remaining:
          $ref: '#/components/headers/RateLimitHeavyRemaining'
        X-Quota-Limit:
          $ref: '#/components/headers/QuotaLimit'
        X-Quota-Remaining:
          $ref: '#/components/headers/QuotaRemaining'
        X-Quota-Reset:
          $ref: '#/components/headers/QuotaReset'
        X-Quota-Warning:
          $ref: '#/components/headers/QuotaWarning'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem:
      description: >-
        Any other error. Every error of this API is a problem details object (RFC 9457,
        application/problem+json) with a stable machine-readable code and a human detail; branch on
        code and treat an unknown one by its HTTP status
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: tk_ token
      x-scopes:
        brands:read: Read brands, their assets, brand.md and analytics
        brands:write: Update a brand's text, links, access and settings
        brands:create: Create brands, delete them to the bin and restore them from it
        brands:domains: Connect, check and remove a brand's custom domain
        brands:files: Upload a brand's icon, logos, banner, social image, favicon and collection files
        brands:requests: List download and view requests and approve or reject them
        webhooks:manage: Add, change and remove webhook endpoints, send test events and read the delivery log
        files:read: List and download files and folders
        files:write: >-
          Create folders, rename and delete files and folders (and restore them from the bin);
          uploads are separate endpoints
        ai:ask: >-
          Ask a question about the library's files and get an answer with sources; it spends AI
          credits like a question in Ask about files (read-only)
        transfers:create: >-
          Create a shareable transfer link from files or folders already in the library, deliver it
          to contacts' client portals, change it (view only, expiry, password) and delete it
        transfers:read: Read a transfer's status
        contacts:create: Add a contact to the workspace
        contacts:read: List and search the workspace's contacts, and read their portal upload use
        contacts:portal: >-
          Turn a contact's client portal access on or off, resend their sign-in email and set their
          portal upload limit
        file_requests:create: Create a public upload link (a file request)
        file_requests:read: List the workspace's file requests
        teams:create: Create a team folder (Pro only, owner or admin)
      description: >-
        Scopes: brands:read (Read brands, their assets, brand.md and analytics); brands:write
        (Update a brand's text, links, access and settings); brands:create (Create brands, delete
        them to the bin and restore them from it); brands:domains (Connect, check and remove a
        brand's custom domain); brands:files (Upload a brand's icon, logos, banner, social image,
        favicon and collection files); brands:requests (List download and view requests and approve
        or reject them); webhooks:manage (Add, change and remove webhook endpoints, send test events
        and read the delivery log); files:read (List and download files and folders); files:write
        (Create folders, rename and delete files and folders (and restore them from the bin);
        uploads are separate endpoints); ai:ask (Ask a question about the library's files and get an
        answer with sources; it spends AI credits like a question in Ask about files (read-only));
        transfers:create (Create a shareable transfer link from files or folders already in the
        library, deliver it to contacts' client portals, change it (view only, expiry, password) and
        delete it); transfers:read (Read a transfer's status); contacts:create (Add a contact to the
        workspace); contacts:read (List and search the workspace's contacts, and read their portal
        upload use); contacts:portal (Turn a contact's client portal access on or off, resend their
        sign-in email and set their portal upload limit); file_requests:create (Create a public
        upload link (a file request)); file_requests:read (List the workspace's file requests);
        teams:create (Create a team folder (Pro only, owner or admin)). Create an API key in
        Settings > API.
security:
  - bearer: []
x-api-lifecycle:
  version: v1
  status: stable
  deprecation_scheduled: false
  minimum_notice_months: 6
  signalled_by:
    - Deprecation response header (RFC 9745)
    - Sunset response header (RFC 8594)
    - Link header with rel=deprecation and rel=sunset
  policy: >-
    v1 only grows (endpoints, optional fields, error codes). A breaking change ships as a new
    version in the path. The old version keeps working for at least 6 months after its Deprecation
    header first appears. No version is deprecated today, so no response carries these headers.
x-error-codes:
  invalid_request:
    status: 400
    title: Invalid request
    meaning: A field is missing, has the wrong type or is out of range.
  invalid_workspace:
    status: 400
    title: Invalid workspace key
    meaning: >-
      The workspace value is malformed. A key is eight lowercase letters and digits (GET /workspaces
      lists them).
  workspace_required:
    status: 400
    title: Workspace key required
    meaning: >-
      No workspace key was sent. Send X-Workspace-Key (or workspace_key) on every call that works
      inside a workspace.
  workspace_key_required:
    status: 400
    title: Workspace id not accepted
    meaning: A workspace id was sent where the eight-character workspace key is required.
  conflicting_workspace:
    status: 400
    title: Conflicting workspace
    meaning: >-
      The workspace is named twice with different values, for example in the header and in the
      query.
  not_supported:
    status: 400
    title: Not supported
    meaning: The operation does not apply to this item, for example a modification time on a folder.
  invalid_name:
    status: 400
    title: Invalid name
    meaning: The name is empty, is . or .., contains / or control characters, or is not valid Unicode.
  name_too_long:
    status: 400
    title: Name too long
    meaning: The name is longer than 255 bytes in UTF-8.
  invalid_destination:
    status: 400
    title: Invalid destination
    meaning: A folder cannot be moved into itself or one of its own subfolders.
  version_too_large:
    status: 400
    title: Version too large
    meaning: The file is too large to save as a new version.
  confirmation_required:
    status: 400
    title: Confirmation required
    meaning: >-
      A destructive or publishing step needs its confirmation: confirm_public: true to make a brand
      public, confirm_delete: true to archive (delete) a brand.
  direct_download_blocked_file_types:
    status: 400
    title: File type blocked for direct download
    meaning: >-
      One or more selected files cannot be sent with download_mode: "direct" for security reasons.
      details.blockedFiles names which, and why.
  unauthorized:
    status: 401
    title: Unauthorized
    meaning: The token is missing, malformed, invalid or revoked.
  legacy_token:
    status: 401
    title: Retired token
    meaning: >-
      The token is an older workspace token and no longer works. Create a new token in Settings >
      API.
  forbidden:
    status: 403
    title: Forbidden
    meaning: >-
      The token lacks the scope this operation needs, or its creator's role in the workspace is not
      enough.
  token_without_scopes:
    status: 403
    title: Token has no scopes
    meaning: The token was created before scopes existed. Create a new token and choose its scopes.
  no_access:
    status: 403
    title: No access to this workspace
    meaning: >-
      The workspace key is unknown, or the person who created the token cannot access that
      workspace. Both answer the same, so keys cannot be probed.
  workspace_suspended:
    status: 403
    title: Workspace suspended
    meaning: >-
      The workspace is suspended, so its API is closed as well. Contact support or the workspace
      owner.
  protected:
    status: 403
    title: Protected item
    meaning: >-
      The item is protected (system, request, team or transfer folders) and cannot be changed
      through the API. details.kind says why.
  domain_taken:
    status: 409
    title: Domain not available
    meaning: >-
      The domain is already used by another brand or another part of Tarkle, or it is attached
      elsewhere. details.reason names which.
  domain_rejected:
    status: 422
    title: Domain rejected
    meaning: The hosting provider refused the domain.
  domain_provider_error:
    status: 502
    title: Domain provider error
    meaning: The hosting provider could not remove the domain. The brand keeps it; retry.
  file_not_uploaded:
    status: 409
    title: File not uploaded
    meaning: Nothing was found at the upload address. PUT the file to the url, then complete the upload.
  invalid_file:
    status: 422
    title: File refused
    meaning: >-
      The uploaded file is too large, the wrong type or not what its name says. The message names
      the reason and the stored file is removed.
  not_found:
    status: 404
    title: Not found
    meaning: The item, upload or brand does not exist in this workspace.
  private_item:
    status: 403
    title: Private item
    meaning: >-
      The item exists but is private, and the person this token acts as cannot open it. Only an
      admin of a workspace with admin privacy sees this answer; ask the owner or the person who made
      it to share it.
  conflict:
    status: 409
    title: Conflict
    meaning: >-
      The request clashes with the current state, for example a file with the same name exists.
      details lists the choices.
  name_taken:
    status: 409
    title: Name already taken
    meaning: A sibling with this name already exists in the folder.
  ambiguous_path:
    status: 409
    title: Ambiguous path
    meaning: Two folders on the path share a name, so the path points at more than one item. Use ids.
  not_readable:
    status: 422
    title: Nothing to read
    meaning: >-
      The file has no text to read: a scan, picture, audio, video or archive. Search and text
      reading cover files with real text only.
  transfer_active:
    status: 409
    title: Active transfer
    meaning: >-
      The item is part of an active transfer. details.confirm_with names the field that confirms
      deleting those transfers.
  incomplete:
    status: 409
    title: Upload incomplete
    meaning: Not every part has arrived. details.missing_parts lists the parts still to send.
  empty_version_not_supported:
    status: 409
    title: Empty version not supported
    meaning: An empty file cannot be saved as a new version. details.choices lists what to send instead.
  size_unreadable:
    status: 409
    title: Size unreadable
    meaning: The source file's size could not be read.
  parent_unavailable:
    status: 409
    title: Parent folder unavailable
    meaning: The folder the item was in is in the bin or gone. Restore that folder first.
  not_multipart:
    status: 409
    title: Not a multipart upload
    meaning: The upload is a single PUT and has no parts to sign.
  not_deleted:
    status: 409
    title: Not in the bin
    meaning: Only an item in the bin can be restored.
  not_an_api_upload:
    status: 409
    title: Not an API upload
    meaning: The upload was not started through the API.
  folder_unresolved:
    status: 409
    title: Folder unresolved
    meaning: The folder of the file could not be located.
  finalizing:
    status: 409
    title: Upload is finalizing
    meaning: The upload is already being completed. Retry shortly.
  expired:
    status: 410
    title: Expired
    meaning: The upload session or the bin retention window has passed.
  upload_expired:
    status: 410
    title: Upload expired
    meaning: The upload is finished or expired. Start it again.
  failed:
    status: 410
    title: Upload failed
    meaning: The upload failed. Start it again.
  file_too_large:
    status: 413
    title: File too large
    meaning: The file is larger than the plan allows.
  storage_full:
    status: 413
    title: Storage full
    meaning: There is not enough storage left. details.limit may carry the plan's limit in bytes.
  too_large:
    status: 413
    title: Too large
    meaning: A recursive listing covers more folders than one call can return. List a smaller folder.
  unprocessable_file:
    status: 422
    title: File could not be processed
    meaning: >-
      The PDF or file could not be changed or converted: it is damaged, password protected, a scan
      with no text for a text tool, has nothing to redact, or its pictures or tables could not be
      read. The message says which. details.not_found lists the texts that were not in the PDF.
  integrity_mismatch:
    status: 422
    title: Integrity check failed
    meaning: >-
      The stored file's SHA-256 differs from the one sent. details.expected and details.stored may
      carry both hashes.
  size_mismatch:
    status: 422
    title: Size mismatch
    meaning: The stored size differs from the size announced when the upload started.
  idempotency_in_progress:
    status: 409
    title: Request still running
    meaning: >-
      A request with the same Idempotency-Key has not finished. Wait Retry-After seconds and send it
      again; you get its answer.
  idempotency_key_reused:
    status: 422
    title: Idempotency key reused
    meaning: >-
      The Idempotency-Key was already used for a different request (another path, query, workspace
      or body). Use a new key.
  rate_limited:
    status: 429
    title: Rate limit exceeded
    meaning: >-
      Too many requests in this minute for this API key, or too many search and AI requests in this
      minute. Wait Retry-After seconds. The message says which limit was hit.
  quota_exceeded:
    status: 429
    title: Daily quota used up
    meaning: >-
      The organization's daily API quota is used up (it is shared by every API key and workspace of
      the organization). Retry-After is the number of seconds until it resets at midnight UTC. A
      plan with a higher quota raises it.
  ai_budget:
    status: 429
    title: AI credits used
    meaning: >-
      The organization's AI credits for the day, week or month are used (or its own AI key's
      budget). The message says when they reset; an owner can add credits in Billing.
  workspace_ai_off:
    status: 403
    title: AI is off for this workspace
    meaning: >-
      An owner or admin of the organization switched AI off for this workspace, so no AI endpoint
      (ask, search, read text) works there. They can turn it on from the workspace list or from
      Billing, Usage.
  slow_down:
    status: 429
    title: Asking too fast
    meaning: Too many questions in a short time. Wait a moment and ask again.
  ask_failed:
    status: 502
    title: The question could not be answered
    meaning: The AI provider could not answer this time, or the question was stopped. Retry.
  ask_timeout:
    status: 504
    title: The question took too long
    meaning: >-
      The answer was not finished in time and was stopped. Ask a narrower question, for example with
      folder set, or fewer files.
  ask_rate_limited:
    status: 429
    title: The AI is busy
    meaning: The AI provider asked us to slow down. Retry in a minute.
  ask_too_large:
    status: 413
    title: The files are too large to read at once
    meaning: >-
      The files the question needed are over what one answer can read. Ask about fewer or smaller
      files, or set folder.
  ask_unavailable:
    status: 503
    title: The AI is not available
    meaning: Tarkle's AI service cannot answer right now. Retry later.
  ask_cancelled:
    status: 499
    title: The question was cancelled
    meaning: The client closed the request before the answer was finished.
  too_many_uploads:
    status: 429
    title: Too many uploads
    meaning: Too many uploads are open at once. Finish or abort some first.
  transfer_too_large:
    status: 413
    title: Transfer too large
    meaning: >-
      The transfer's total size is larger than the plan's maximum transfer size. details.limit
      carries the limit in bytes.
  transfer_monthly_limit:
    status: 429
    title: Monthly transfer limit reached
    meaning: >-
      The plan's monthly transfer count has been reached. details.limit and details.currentUsage
      carry the numbers.
  file_not_found:
    status: 404
    title: File not found
    meaning: The file the new version belongs to does not exist any more.
  upload_not_found:
    status: 404
    title: Upload not found
    meaning: The version upload does not exist or was cleaned up. Start it again.
  version_unavailable:
    status: 404
    title: Version unavailable
    meaning: The version this upload was based on is no longer available.
  file_in_transfer:
    status: 409
    title: File is in a transfer
    meaning: >-
      A transfer uses this file. Confirm the transfer update in the app, or switch on automatic
      transfer updates in the workspace's file settings.
  upload_in_progress:
    status: 409
    title: Version upload in progress
    meaning: Someone else is already uploading a new version of this file. Retry shortly.
  current_version_changed:
    status: 409
    title: File changed meanwhile
    meaning: The file got another version while this upload was running. Upload again.
  storage_usage_unreadable:
    status: 409
    title: Storage usage unreadable
    meaning: Storage usage could not be verified, so nothing was saved. Retry.
  storage_limit_exceeded:
    status: 413
    title: Storage limit exceeded
    meaning: >-
      There is not enough storage for this version. Older versions count toward storage until they
      expire.
  version_failed:
    status: 500
    title: Version could not be saved
    meaning: The new version could not be saved. Retry; if it persists, contact support.
  server_error:
    status: 500
    title: Server error
    meaning: Something went wrong on our side. Retry; if it persists, contact support.
  storage_unavailable:
    status: 502
    title: Storage unavailable
    meaning: The storage backend failed. Nothing was created; retry.
  unavailable:
    status: 503
    title: Service unavailable
    meaning: The endpoint is switched off or the plan could not be confirmed. Retry later.
  entitlement_unresolved:
    status: 503
    title: Plan could not be resolved
    meaning: The plan could not be confirmed. Retry.
paths:
  /brands:
    get:
      operationId: listBrands
      summary: List brands
      description: >-
        Lists the brand pages of the workspace as short summaries; use getBrand for one in full.
        Page with limit and next_cursor. Needs the brands:read scope, and the token's creator must
        be an owner or admin of the workspace.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: limit
          in: query
          description: 1 to 100, default 25
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          description: 'next_cursor from the previous page. Opaque: do not build or parse it'
          schema:
            type: string
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createBrand
      summary: Create a brand
      description: >-
        Adds a brand page. name is required; the slug defaults to the name (lower case letters,
        digits and dashes). The plan's brand page limit applies exactly as in the app: at the limit
        the call is refused with 403 forbidden (details.entitlement names the limit), and a slug
        already used in the workspace is 409 name_taken. A new brand is always a private draft and
        not public; send password (API only, 8 to 72 bytes) to protect it from the start, and open
        it later with updateBrand (which has its own confirmation for going public). Needs
        brands:create.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandCreate'
      security:
        - bearer:
            - brands:create
      x-required-scope: brands:create
      responses:
        '201':
          description: The new brand (a private draft)
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}:
    get:
      operationId: getBrand
      summary: Get a brand
      description: >-
        Returns one brand in full: text, social links, colors, fonts, access mode, tracking ids, SEO
        fields, team, press and its public URLs. Address it by id (uuid) or slug. Needs brands:read.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteBrand
      summary: Delete a brand (archives it, restorable)
      description: >-
        The API never deletes a brand for good: this ARCHIVES it. The page goes offline and answers
        404, it is not listed in the app, its slug and its place under the plan's brand limit are
        freed, and its domains are detached from hosting and are not restored. The brand, its files
        and its settings are kept without any time limit, so restoreArchivedBrand can bring it back
        at any time. Access requests, analytics and the kit link are not kept. Needs confirm_delete:
        true (query or body), otherwise 400 confirmation_required. Needs brands:create.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: confirm_delete
          in: query
          description: Must be true; the body field of the same name works too
          schema:
            type: boolean
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - brands:create
      x-required-scope: brands:create
      responses:
        '200':
          description: 'The brand is archived (archived: true)'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchivedBrand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateBrand
      summary: Update a brand
      description: >-
        Changes the brand fields you send and leaves the rest alone. Send at least one field;
        unknown fields are refused. The slug, passwords and domains cannot be changed here. A team
        member's photo and a guideline section's images can be sent by address (photo_url, images:
        [{url, kind, caption}]): they are fetched after the text is saved, and the answer's pictures
        list says which worked; a picture that fails never undoes the text. Pictures can also be
        removed with removeBrandFile. Setting access to public on a brand that is not public yet
        needs confirm_public: true, otherwise the call is refused with 400 confirmation_required.
        Returns the whole brand after the change. Needs brands:write.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandPatch'
      security:
        - bearer:
            - brands:write
      x-required-scope: brands:write
      responses:
        '200':
          description: The brand after the change
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /archived-brands:
    get:
      operationId: listArchivedBrands
      summary: List archived brands
      description: >-
        Lists the brands deleted through the API (archived), newest first. They never expire. Needs
        brands:create.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
      security:
        - bearer:
            - brands:create
      x-required-scope: brands:create
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchivedBrandList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /archived-brands/{brand}/restore:
    post:
      operationId: restoreArchivedBrand
      summary: Restore an archived brand
      description: >-
        Puts an archived brand back with the same id and content. The plan's brand page limit
        applies as in the app (403 forbidden). If its slug is used now, send another slug in the
        body, otherwise 409 name_taken. Domains are not restored; connect them again. Needs
        brands:create.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: The id (uuid) of the archived brand from listArchivedBrands
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandRestore'
      security:
        - bearer:
            - brands:create
      x-required-scope: brands:create
      responses:
        '200':
          description: The restored brand
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/domain:
    get:
      operationId: getBrandDomain
      summary: Check a brand's domain
      description: >-
        Returns the brand's custom domain and how far its setup is: status
        (ownership_verification_required, dns_configuration_required, certificate_pending or active)
        and the DNS records to add, with the same dns_provider, dns_zone and dns_guide as
        setBrandDomain. It re-checks with the hosting provider first and stores what it finds, like
        opening the domain in the app; provider_unavailable is true when the provider could not be
        reached and the stored values are returned. 404 when the brand has no domain. Needs
        brands:domains.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
      security:
        - bearer:
            - brands:domains
      x-required-scope: brands:domains
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandDomain'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    put:
      operationId: setBrandDomain
      summary: Connect a domain to a brand
      description: >-
        Connects a custom domain to the brand, or replaces the one it has (a brand has at most one).
        The same rules as the app apply: the plan's brand page domain limit (403 forbidden with
        details.entitlement BRAND_PAGE_DOMAIN_LIMIT; Free allows none, Pro has no limit), a domain
        used by another brand or another part of Tarkle is 409 domain_taken, and the hosting
        provider can refuse it (422 domain_rejected) or be unavailable (503). Returns the domain
        with the DNS records to add at your DNS host, plus dns_provider (who hosts the DNS, found
        from the nameservers), dns_zone and dns_guide: the records named relative to the zone,
        numbered steps, and how to apply them with an API or MCP tool the person already has
        (Cloudflare, Vercel, Route 53 and others). An assistant with such a tool can add
        dns_guide.records itself and then poll getBrandDomain until status is active; without one it
        reads the steps to the person. Call getBrandDomain later to follow the setup. Sending the
        same domain again is safe. Needs brands:domains.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandDomainSet'
      security:
        - bearer:
            - brands:domains
      x-required-scope: brands:domains
      responses:
        '200':
          description: The domain and the DNS records to add
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandDomain'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteBrandDomain
      summary: Remove a brand's domain
      description: >-
        Disconnects the domain from hosting and from the brand. The brand page itself stays. A
        domain the provider holds for another account is 409 conflict, one that stays connected is
        502 domain_provider_error and the brand keeps it. Needs brands:domains.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - brands:domains
      x-required-scope: brands:domains
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandDomainDeleted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brand-lookup:
    post:
      operationId: lookupBrandFromDomain
      summary: Look up a brand from its website address
      description: >-
        Searches public sources for a website address (the same step the app runs when you start a
        brand from a domain) and returns suggestions: brand is a body you can send as it is to
        createBrand or updateBrand (name, summary, story, industry, size, company_type,
        year_founded, url, social links, colors, Google fonts), files holds picture addresses to
        import with the brand file upload (import_url), sources says which provider gave each value
        and missing lists what was not found. Nothing is saved and no workspace is needed. Check the
        suggestions before you save them: they come from third parties. The call spends provider
        credits, so it counts as a search request: 5 units of the daily quota and the plan's search
        and AI limit a minute per key (keys made before the rollout keep 20 a minute until the grace
        ends). 404 when nothing is known about the site. Needs brands:read.
      tags:
        - Brands
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandLookupRequest'
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: Suggestions; nothing is saved
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandLookup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/files:
    post:
      operationId: startBrandFileUpload
      summary: Start uploading a brand file
      description: >-
        Step 1 of 2. Send the slot the file is for: icon, main_logo, banner, social_image, favicon
        (each replaces the current one), logo (an extra logo), asset (a collection file), team_photo
        (one team member's photo, replaces the current one) or guideline_image (adds a picture to a
        guideline section). Optionally send size and filename to be refused early. The answer holds
        a signed upload address: PUT the file bytes to upload.url (it expires after expires_in
        seconds), then call completeBrandFileUpload with file_id. Nothing is attached yet. The
        limits are the brand editor's: logos and icons PNG, JPG, WebP or SVG up to 10 MB; banners
        and social images PNG, JPG or WebP up to 10 MB; favicons also ICO, up to 2 MB; collection
        files of any type up to 100 MB. A brand can have 20 extra logos; asset needs a brand without
        older-editor images (409 otherwise). Needs brands:files.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandFileStart'
      security:
        - bearer:
            - brands:files
      x-required-scope: brands:files
      responses:
        '201':
          description: Where to PUT the file, and the file_id to complete it with
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandFileUpload'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: removeBrandFile
      summary: Remove a file from a brand
      description: >-
        Takes one file off the brand and deletes the stored file unless something of the brand still
        uses it. Send slot as a query parameter. icon, main_logo, banner, social_image and favicon
        need only the slot. logo needs id (the logo id from listBrandAssets), asset needs id (the
        collection file id from listBrandAssets), team_photo needs member_id (or member_name when
        the member has no id) and guideline_image needs section_id and id (the image id from the
        brand's guidelines). It is the editor's own all-or-nothing save. Nothing there is 404
        not_found; older-editor images on the brand block asset removal (409). Needs brands:files.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: slot
          in: query
          required: true
          description: >-
            icon, main_logo, banner, social_image, favicon, logo, asset, team_photo or
            guideline_image
          schema:
            type: string
            enum:
              - icon
              - main_logo
              - banner
              - social_image
              - favicon
              - logo
              - asset
              - team_photo
              - guideline_image
        - name: id
          in: query
          description: 'logo, asset and guideline_image: the id of the file'
          schema:
            type: string
        - name: member_id
          in: query
          description: 'team_photo: the team member''s id'
          schema:
            type: string
        - name: member_name
          in: query
          description: 'team_photo: the member''s name, when the member has no id'
          schema:
            type: string
        - name: section_id
          in: query
          description: 'guideline_image: the guideline section''s id'
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - brands:files
      x-required-scope: brands:files
      responses:
        '200':
          description: The file is removed
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandFileRemoved'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/files/import:
    post:
      operationId: importBrandFile
      summary: Import a brand file from a web address
      description: >-
        Both upload steps in one call, for a picture that is already on the web (a logo returned by
        lookupBrandFromDomain, say). Send slot and url (https, public) and, for logo or asset, the
        fields completeBrandFileUpload takes. The server fetches the address (public hosts only,
        redirects checked), stores it and attaches it with the same checks as an upload: size, type
        and real content. An address that is not a public image, is too large or fails the checks is
        422 invalid_file and nothing is attached. Returns the attached file (201). Needs
        brands:files.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandFileImport'
      security:
        - bearer:
            - brands:files
      x-required-scope: brands:files
      responses:
        '201':
          description: The file is fetched and attached
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandFileAttached'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/files/{file}/complete:
    post:
      operationId: completeBrandFileUpload
      summary: Finish a brand file upload
      description: >-
        Step 2 of 2. Checks what was stored at the upload address (size, type and the real first
        bytes, the same rules as the brand editor) and attaches it. A file that fails is removed and
        answered 422 invalid_file; nothing stored yet is 409 file_not_uploaded. An icon, logo,
        banner, social image or favicon replaces the current one, and the old file is removed unless
        the brand still uses it. For logo you may send name, type and usage; for asset send
        collection_id (or collection_name to start a collection), name and type; for team_photo send
        member_id (or member_name); for guideline_image send section_id and optionally kind (image,
        do, dont) and caption. Completing the same file again returns the same answer with
        already_attached true and changes nothing. The file_id only works for the brand and slot it
        was made for. Needs brands:files.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: file
          in: path
          required: true
          description: The file_id from startBrandFileUpload
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandFileComplete'
      security:
        - bearer:
            - brands:files
      x-required-scope: brands:files
      responses:
        '200':
          description: The file is attached
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandFileAttached'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/assets:
    get:
      operationId: listBrandAssets
      summary: List a brand's files with short-lived download links
      description: >-
        Lists the brand's icon, main logo and banner, its logos and its file collections, each file
        with a short-lived download link. The links expire (links_expire is always true), so list
        again when you need fresh ones. Needs brands:read.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandAssets'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/markdown:
    get:
      operationId: getBrandMarkdown
      summary: The brand as markdown (brand.md)
      description: >-
        Returns the brand as one markdown document (brand.md), the form AI assistants read best. The
        response is text/markdown, not JSON. Needs brands:read.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: The brand as markdown
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            text/markdown:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/analytics:
    get:
      operationId: getBrandAnalytics
      summary: Page views, downloads and requests
      description: >-
        Returns page views, downloads and requests for the brand as totals and daily series. period
        is 30d (default), 90d or all. Needs brands:read.
      tags:
        - Brands
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: period
          in: query
          description: 30d (default), 90d or all
          schema:
            type: string
            enum:
              - 30d
              - 90d
              - all
            default: 30d
      security:
        - bearer:
            - brands:read
      x-required-scope: brands:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandAnalytics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/requests:
    get:
      operationId: listBrandRequests
      summary: List download and view requests
      description: >-
        Lists the download and view requests people sent from the brand page. Filter with status
        (pending, approved or rejected) and page with next_cursor. Needs brands:requests.
      tags:
        - Requests
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: limit
          in: query
          description: 1 to 100, default 25
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          description: 'next_cursor from the previous page. Opaque: do not build or parse it'
          schema:
            type: string
        - name: status
          in: query
          description: pending, approved or rejected
          schema:
            type: string
            enum:
              - pending
              - approved
              - rejected
      security:
        - bearer:
            - brands:requests
      x-required-scope: brands:requests
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /files:
    get:
      operationId: listFiles
      summary: >-
        List the files and folders inside a folder of the library (folders first, then files; the
        root by default)
      description: >-
        In a workspace with admin privacy on, an ADMIN token never sees private items it cannot
        open: `locked_count` says how many private folders were left out, and include_locked=true
        lists them as bare placeholders ({id, type, name, parent_id, locked: true, visibility:
        private}); opening one answers 403 private_item. Lists what is inside one folder: folders
        first, then files, each in id order so a cursor never skips or repeats an entry. The library
        root is the default; pick another folder with folder (a folder id) or path (for example
        /photos/2026), not both. With recursive=true and a type, every descendant comes back as one
        flat list with absolute paths (a subtree above 5,000 folders is refused with 413 too_large).
        Page with limit and next_cursor. Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: folder
          in: query
          description: A folder id (uuid); omit for the root. Not together with path
          schema:
            type: string
            format: uuid
        - name: path
          in: query
          description: A path of folder names such as /photos/2026. Not together with folder
          schema:
            type: string
        - name: recursive
          in: query
          description: >-
            true to list EVERY descendant as one flat list with absolute paths (needs type); a
            subtree above 5,000 folders is refused
          schema:
            type: boolean
        - name: type
          in: query
          description: file or folder; required with recursive=true
          schema:
            type: string
            enum:
              - file
              - folder
        - name: limit
          in: query
          description: 1 to 1000, default 100
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: cursor
          in: query
          description: 'next_cursor from the previous page. Opaque: do not build or parse it'
          schema:
            type: string
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}:
    get:
      operationId: getFile
      summary: Get one file or folder, with its path and whether it is protected
      description: >-
        Returns one file or folder by id, with its absolute path and whether a protection rule
        applies to it (protected, protection_kind). A file id is digits, a folder id is a uuid.
        Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateFile
      summary: >-
        Rename and/or move a file or folder, and/or set a file's own modification time (body: name,
        parent_id: a folder id or null for the root, modified_at)
      description: >-
        Renames and/or moves a file or folder, and/or sets a file's own modification time
        (modified_at, files only). Send at least one of name, parent_id (a folder id, or null for
        the library root) and modified_at; other keys such as a path or a parent name are refused. A
        name already used in the destination is 409 name_taken. Protected items (system, request or
        team folders, or an item a paid transfer holds) are 403 protected. Returns the item after
        the change. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilePatch'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: The item after the change
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteFile
      summary: >-
        Move a file or folder to the bin; if a transfer holds it, 409 transfer_active until
        confirm_delete_transfers=true
      description: >-
        Moves a file or folder to the bin, where the app's retention rule applies and restoreFile
        can bring it back. If a transfer holds the item the answer is 409 transfer_active and its
        details name the transfers; repeat with confirm_delete_transfers=true to delete those
        transfers as well. Protected items are 403 protected. Returns deleted: true and the ids of
        any transfers deleted with it. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - name: confirm_delete_transfers
          in: query
          description: true to also delete the transfers that hold the item (only the exact text true counts)
          schema:
            type: boolean
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: Moved to the bin
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/download:
    get:
      operationId: getFileDownloadLink
      summary: A short-lived download link for a file
      description: >-
        Returns a signed URL for a file's bytes. The URL works without the token for 15 minutes
        (expires_in is in seconds): fetch it at once, or ask again for a fresh one. Folders have no
        download link (400). Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownload'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/search:
    get:
      operationId: searchFiles
      summary: >-
        Search the words inside the library's files; returns the best matching passages with file
        id, page and a snippet
      description: >-
        Finds the passages of the workspace's files (PDF, Word, text, Markdown, subtitles) that best
        match the words of q. Each result has file_id, name, folder_id, page (PDFs) and a snippet;
        coverage says how many files exist, were searched, cannot be searched as text (pictures,
        audio, video, scans) or are still waiting to be read (call again to continue). Only files
        the token's person can open are searched. No model runs and no credits are used. It counts
        as a search request: 5 units of the organization's daily quota and the plan's search and AI
        limit a minute per key. Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: q
          in: query
          required: true
          description: The words to look for (up to 500 characters)
          schema:
            type: string
        - name: folder
          in: query
          description: Only search inside this folder and its subfolders (a folder id)
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: 1 to 20, default 8
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 8
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileSearch'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /ai/ask:
    post:
      operationId: askFiles
      summary: 'Ask a question about the files and get an answer with sources (body: question, folder, mode)'
      description: >-
        Answers one question from the workspace's files, written by the same code as Ask about files
        in the app, and returns { answer, sources, credits_used, paid_by, mode, notes }. In answer
        the files are cited as [1], [2]; sources lists them with file_id (the files API's id, null
        when unknown), name and pages. Body: question (required, up to 4000 characters), history
        (optional, up to 20 earlier messages of {role, content}, oldest first, for a follow-up),
        folder (a folder id: only that folder and its subfolders are read), mode (basic, the
        default, or deep: slower and thorough, Pro plans and organizations with their own AI key).
        It only reads: nothing is changed, nothing is saved: each call is a separate question unless
        you send history. Only files the token's person can open are read. THIS SPENDS AI CREDITS
        exactly like a question in the app (the plan's credits, extra credits, or the organization's
        own AI key): credits_used says how many; when the credits for the period are used the call
        is 429 ai_budget, and a person asking far too fast gets 429 slow_down. A call can run for
        minutes (up to 5), so set a long client timeout. Search and reading with no credits:
        searchFiles and getFileText. It counts as an AI request: 1 unit of the daily quota and the
        plan's search and AI limit a minute per key (its real cost is the credits above). Needs
        ai:ask; a token made before this scope existed does not have it, so make a new one in
        Settings > API.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      security:
        - bearer:
            - ai:ask
      x-required-scope: ai:ask
      responses:
        '200':
          description: The answer with its sources and the credits it used
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskAnswer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/text:
    get:
      operationId: getFileText
      summary: The text of one file, by page range (about 12,000 characters per call)
      description: >-
        Returns the readable text of one file. For a PDF pick pages with from_page and to_page;
        truncated says more follows. 404 for a file the token's person cannot open; 422 not_readable
        when the file has no text to read (a scan, picture, audio, video or archive). Needs
        files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - name: from_page
          in: query
          description: First page (PDFs)
          schema:
            type: integer
            minimum: 1
        - name: to_page
          in: query
          description: Last page (PDFs)
          schema:
            type: integer
            minimum: 1
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileText'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /folders:
    post:
      operationId: createFolder
      summary: 'Create a folder (body: name, parent_id optional; a taken name is a 409)'
      description: >-
        Creates a folder in the library root or inside parent_id. A name already used in that folder
        is 409 name_taken. Returns the new folder with 201. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreate'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The new folder
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /workspaces:
    get:
      operationId: listWorkspaces
      summary: >-
        The workspaces this token can be used for, with the workspace_key to send as X-Workspace-Key
        (needs any API access)
      description: >-
        Lists the workspaces this token can act on, with the workspace_key to send in
        X-Workspace-Key on every other call. Start here: it needs only a valid token that has at
        least one scope (any scope works) and no workspace key. relationship says how the token's
        creator is connected to each workspace (owner, member or linked).
      tags:
        - Files
      parameters: []
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/by-path:
    get:
      operationId: getFileByPath
      summary: >-
        One file or folder by its path, without listing the folder around it (404 not found, 409
        ambiguous_path)
      description: >-
        Returns one file or folder by its path, for example /photos/2026/a.jpg, without listing the
        folder around it. 404 not_found when nothing is there; 409 ambiguous_path when more than one
        item has that path. Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: path
          in: query
          required: true
          description: A path such as /photos/2026/a.jpg
          schema:
            type: string
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/restore:
    post:
      operationId: restoreFile
      summary: Restore a file or folder from the bin (same retention rule as the app)
      description: >-
        Restores a file or folder from the bin, under the same retention rule as the app. 409
        not_deleted when the item is not in the bin; 409 parent_unavailable when its folder is gone;
        410 expired when the retention period has passed. Returns the restored item. Needs
        files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: The restored item
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/copy:
    post:
      operationId: copyFile
      summary: 'Copy a file inside storage (body: parent_id, name; a taken name is 409, plan limits apply)'
      description: >-
        Copies a file inside storage, with no download or re-upload. parent_id is the destination
        folder (null for the library root; omitted keeps the original's folder) and name the new
        name (omitted keeps the original's). A copy never renames silently: a taken name is 409
        name_taken. Plan limits apply (413 storage_full, 413 file_too_large). Folders cannot be
        copied (400 not_supported). Returns the copy with 201. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileCopy'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The copy
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryWithPath'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/pdf-edit:
    post:
      operationId: editPdf
      summary: >-
        Page tools on a PDF, saved as a new PDF (merge, keep or remove, reorder, rotate, crop, blank
        pages, page numbers, watermark, title and author)
      description: >-
        Makes a NEW PDF from this one with the page tools in the body; the source is never changed.
        Send at least one of merge_file_ids, keep or remove (pages like 1-3,5), order, rotate, crop
        (millimetres; the cut-off part is hidden, not deleted), blank_after, blank_at_start,
        page_numbers, watermark (a text drawn over every page, which hides nothing underneath),
        title, author. They apply in that order. name and folder_id choose the new file (default:
        '<name> (edited).pdf' next to the source). The same limits as the chat (40 MB a PDF, up to
        2,000 pages, up to 10 PDFs merged). A password-protected PDF is 422 unprocessable_file; a
        taken name is 409 name_taken; plan limits apply (413). Needs files:write; 20 calls a minute
        per token.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfEditRequest'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The new PDF
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileToolResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/convert:
    post:
      operationId: convertFile
      summary: >-
        Convert a file into a new file (PDF to text, pictures, Word, Excel or split parts; pictures
        or an Office file to PDF; OCR, redact, compress, protect, unlock)
      description: >-
        Makes a NEW file from this one; the source is never changed. `to` selects the conversion:
        text (a .txt), images (PNG or JPG per page, in a zip, up to 30 pages), split (a zip of PDFs;
        ranges 'each' or '1-3,4-6'), word (the text as a .docx), excel (the tables found by position
        as a .xlsx; none found is 422), pdf (the source is a picture, with more_file_ids for more
        pictures, or one Word, Excel or PowerPoint file converted by LibreOffice in an isolated
        sandbox, up to about half a minute), ocr (a searchable PDF; English, up to 8 scanned pages a
        run), redact (terms and/or emails: every page with a match becomes a picture, so the text is
        gone from the file; every term must exist), compress (level light, medium or strong),
        protect (password: AES-256) and unlock (password: the PDF's current one). The password is
        used for this call only and is never stored or logged. name and folder_id choose the new
        file. Needs files:write; 20 calls a minute per token.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertRequest'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The new file
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileToolResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /documents:
    post:
      operationId: createDocument
      summary: Write a new document from content (PDF, Word, PowerPoint, Excel, CSV or Markdown)
      description: >-
        Writes a NEW file from the content in the body. format pdf, docx or pptx take `markdown`
        (for pptx an outline: `# Title` is the title slide and its first line the subtitle, each `##
        Heading` a slide, bullets become bullet points, a table gets its own slide); md takes
        `markdown`; xlsx and csv take `table` ({ columns, rows }: up to 12 columns and 500 rows of
        text; numbers become numbers in Excel, codes with leading zeros stay text). `sources` are
        ids of files the document is based on (digits, up to 10): a true Sources list is added from
        their real names. `name` is required (the extension is added or corrected); the file goes to
        folder_id (null or omitted: the library root). The same generators and limits as the chat
        (60,000 characters of Markdown). A taken name is 409 name_taken; plan limits apply (413).
        Needs files:write; 20 calls a minute per token.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreate'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The new document
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileToolResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/fill-template:
    post:
      operationId: fillTemplate
      summary: Fill a Word template into a new .docx ({placeholders}, lists, repeated table rows)
      description: >-
        The file in the path is a Word (.docx) template with {placeholders}; it is never changed.
        `values` maps each placeholder name to text, or to a list of rows ([{ item: 'Setup', price:
        '100' }]) for a repeated block or table row. Every placeholder must have a value and every
        value a placeholder: otherwise 422 unprocessable_file with details.missing, details.unused
        and details.placeholders (the template's own placeholder names). Placeholder names are used
        exactly as sent (they are never renamed). name and folder_id choose the new file (default
        '<template> (filled).docx' next to the template). Needs files:write; 20 calls a minute per
        token.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateFill'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The filled document
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileToolResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /files/{id}/office-edit:
    post:
      operationId: editOfficeFile
      summary: >-
        Change a copy of a Word, PowerPoint or Excel file (replace text, insert, change cells,
        append rows)
      description: >-
        Saves the changes as a NEW file; the source is never changed. The kind of the file in the
        path decides the fields. .docx: edits ([{ find, replace }], exact text), inserts (a
        paragraph list, a table or a picture by file id of a PNG, JPG or GIF, placed after some text
        or at the end), track_changes (the changes become tracked changes by Tarkle that the person
        accepts or rejects in Word). .pptx: edits ([{ find, replace }] on every slide where the text
        appears). .xlsx: cells ([{ sheet, cell, value }], up to 100) and append_rows ([{ sheet, rows
        }], up to 200 rows); a cell with a formula, a merged cell, or a workbook with charts,
        pictures, pivot tables or macros is refused. Every text, anchor or sheet named must exist:
        422 unprocessable_file with details.not_found, details.anchors_not_found and
        details.sheets_not_found. Needs files:write; 20 calls a minute per token.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A file id (digits) or a folder id (uuid)
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeEdit'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '201':
          description: The edited copy
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileToolResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /usage:
    get:
      operationId: getUsage
      summary: Storage in use and the plan's limit (null when there is none)
      description: >-
        Returns the storage the workspace uses and its plan's limit, in bytes. limit_bytes and
        free_bytes are null when the plan has no limit. Needs files:read.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
      security:
        - bearer:
            - files:read
      x-required-scope: files:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /uploads:
    post:
      operationId: startUpload
      summary: >-
        Start an upload into a folder (body: name, size, folder_id, content_type, sha256,
        on_conflict); returns signed URLs, or creates an empty file directly when size is 0
      description: >-
        Starts an upload of size bytes into folder_id (the library root by default). A small file
        gets one signed URL; a larger file gets mode multipart, a part_size and the first 20 signed
        part URLs (signUploadParts returns more). PUT the bytes to each URL, then call
        completeUpload. A file of size 0 is created at once (action created). When the name already
        exists in the folder and the app's duplicate rule would ask, the call is 409 conflict and
        details.choices lists your answers: send one as on_conflict (version adds a new version of
        the existing file, separate keeps both under a numbered name, skip uploads nothing). In
        other cases the same rule as the app applies: depending on the plan the existing file gets a
        new version or the new file gets a numbered name, and an identical file is skipped (action
        skip, status 200). A version upload answers with kind version and the existing file_id; the
        rest of the flow is the same. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadStart'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: 'Nothing to upload: an identical file is already there (action skip)'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSkipped'
        '201':
          description: The upload started (action upload), or a file of size 0 was created (action created)
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UploadStarted'
                  - $ref: '#/components/schemas/UploadStartedVersion'
                  - $ref: '#/components/schemas/FileCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /uploads/{id}:
    get:
      operationId: getUpload
      summary: Where an upload stands (never finishes it)
      description: >-
        Returns where an upload you started stands: status, parts_received for a multipart upload
        and, once finished, the file. It only reads and never finishes the upload. For a multipart
        version upload pass the multipart_id that startUpload returned. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: An upload id (uuid)
          schema:
            type: string
            format: uuid
        - name: multipart_id
          in: query
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
          schema:
            type: string
            maxLength: 1023
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UploadStatus'
                  - $ref: '#/components/schemas/UploadStatusVersion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: abortUpload
      summary: Abort an unfinished upload
      description: >-
        Aborts an unfinished upload and discards the bytes sent so far. Returns aborted: true. For a
        multipart version upload pass the multipart_id that startUpload returned. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: An upload id (uuid)
          schema:
            type: string
            format: uuid
        - name: multipart_id
          in: query
          description: 'For a multipart version upload: the multipart_id that startUpload returned'
          schema:
            type: string
            maxLength: 1023
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: Aborted
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAborted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /uploads/{id}/parts:
    post:
      operationId: signUploadParts
      summary: Fresh signed URLs for a range of parts (from_part, count up to 100)
      description: >-
        Returns fresh signed URLs for a range of parts of a multipart upload: from_part (default 1)
        and count (default 20, up to 100). Use it when the first URLs have expired or to sign the
        next batch. A single-part upload answers 409 not_multipart; an expired upload 410. Needs
        files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: An upload id (uuid)
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadPartsRequest'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadParts'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /uploads/{id}/complete:
    post:
      operationId: completeUpload
      summary: >-
        Finish the upload into the folder chosen at the start; optional body: sha256, modified_at
        (multipart_id is stored by the server); returns the file
      description: >-
        Finishes the upload: puts the file in the folder chosen at the start and returns it. If
        bytes are missing the answer is 409 incomplete and nothing is lost: details.missing_parts
        lists the parts to send (at most 1000 are listed); send them and call again. Calling it
        again after success returns the same file. Optional sha256 (checked by the server up to 100
        MiB, kept as the client's claim above that) and modified_at (the file's own modification
        time) are recorded on the file. For a version upload, version_created says whether a new
        version was made (false when the bytes equal the current version). Bytes that do not match
        the announced size or the sha256 are 422. Needs files:write.
      tags:
        - Files
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: An upload id (uuid)
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadCompleteRequest'
      security:
        - bearer:
            - files:write
      x-required-scope: files:write
      responses:
        '200':
          description: The finished file
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCompleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /brands/{brand}/requests/{request}:
    post:
      operationId: decideBrandRequest
      summary: Approve or reject a request
      description: >-
        Approves or rejects a request. A request that is already decided is a 409 conflict. emailed
        in the result says whether the requester was notified by email. Needs brands:requests.
      tags:
        - Requests
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: brand
          in: path
          required: true
          description: Brand id (uuid) or slug
          schema:
            type: string
        - name: request
          in: path
          required: true
          description: Request id (uuid) from the requests list
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Decision'
      security:
        - bearer:
            - brands:requests
      x-required-scope: brands:requests
      responses:
        '200':
          description: The decision
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks:
    get:
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      description: >-
        Lists the workspace's webhook endpoints: where events are sent, which events each asked for,
        whether it is on, and why it was switched off if it was. A signing secret is never in this
        list. Needs webhooks:manage, and the token's creator must be an owner or admin of the
        workspace.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createWebhookEndpoint
      summary: Add a webhook endpoint
      description: >-
        Adds an address that Tarkle sends signed events to. The address must be https and public.
        The signing secret is in this answer only; keep it. A workspace can have up to 20 endpoints.
        Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreate'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '201':
          description: The endpoint and its signing secret
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks/{id}:
    get:
      operationId: getWebhookEndpoint
      summary: Get a webhook endpoint
      description: Returns one endpoint. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateWebhookEndpoint
      summary: Change a webhook endpoint
      description: >-
        Changes the address, the events, the description or whether the endpoint is on. Turning it
        on again clears its failure count. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointUpdate'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: The endpoint after the change
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteWebhookEndpoint
      summary: Delete a webhook endpoint
      description: Deletes the endpoint, its secret and its delivery log. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks/{id}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      summary: Rotate the signing secret
      description: >-
        Makes a new signing secret and returns it once. For the next 24 hours every delivery is
        signed with both the new and the old secret (two v1 values in the Tarkle-Signature header),
        so a receiver can switch without missing one. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: The new secret
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretRotated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks/{id}/test:
    post:
      operationId: sendWebhookTestEvent
      summary: Send a test event
      description: >-
        Sends one webhook.test event to the endpoint now and returns what happened. One try, no
        retries, and it does not change the endpoint's state, so you can test an endpoint that is
        switched off. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: What happened to the test event
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks/{id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      summary: List an endpoint's deliveries
      description: >-
        The latest deliveries of an endpoint, newest first, with the status and every attempt.
        Deliveries are kept for 7 days. limit is 1 to 100, default 25. Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: 1 to 100, default 25
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /webhooks/{id}/deliveries/{delivery}/redeliver:
    post:
      operationId: redeliverWebhookEvent
      summary: Send an event again
      description: >-
        Sends an earlier event again, now, as a fresh run of tries. The endpoint must be on (409
        otherwise). Needs webhooks:manage.
      tags:
        - Webhooks
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A webhook endpoint id (uuid) from listWebhookEndpoints
          schema:
            type: string
            format: uuid
        - name: delivery
          in: path
          required: true
          description: A delivery id (uuid) from listWebhookDeliveries
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - webhooks:manage
      x-required-scope: webhooks:manage
      responses:
        '200':
          description: What happened to the resent event
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /transfers:
    post:
      operationId: createTransfer
      summary: Create a shareable transfer link
      description: >-
        Creates a shareable link from one or more files or folders already in the library (upload
        with POST /uploads first). Plain file transfers only: no video, audio or canvas transfers,
        no payment, no recipient emails -- those stay app-only. access is public or password
        (password also needs password). The workspace's own transfer-size and monthly-transfer-count
        plan limits apply exactly as in the app: 413 transfer_too_large or 429
        transfer_monthly_limit. Needs transfers:create.
      tags:
        - Transfers
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferCreate'
      security:
        - bearer:
            - transfers:create
      x-required-scope: transfers:create
      responses:
        '201':
          description: The new transfer, with its share link
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /transfers/{id}:
    get:
      operationId: getTransfer
      summary: Get a transfer
      description: >-
        Returns one transfer's current status and share link, address it by id. A transfer created
        in the app as video, audio, canvas or paid is not exposed here (404) -- this endpoint only
        reads plain file transfers. Needs transfers:read.
      tags:
        - Transfers
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A transfer id, from createTransfer's answer
          schema:
            type: string
      security:
        - bearer:
            - transfers:read
      x-required-scope: transfers:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteTransfer
      summary: End a transfer early
      description: >-
        Deletes the transfer: its share link stops working at once. Needs transfers:create, the same
        scope that made it.
      tags:
        - Transfers
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A transfer id, from createTransfer's answer
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - transfers:create
      x-required-scope: transfers:create
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferDeleted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateTransfer
      summary: 'Change a transfer: view only, expiry or password'
      description: >-
        Changes a plain transfer after it was made. view_only false lets the people it was delivered
        to download its files in their client portal; true takes that back. expires_at (a future
        date at most three years ahead, or null to remove) and password (4 to 100 characters, or
        null to remove) follow the app's own transfer settings rules. A paid transfer is refused
        (409 conflict): its payment stays the gate. Answers the transfer as getTransfer does. Needs
        transfers:create.
      tags:
        - Transfers
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A transfer id, from createTransfer's answer
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferUpdate'
      security:
        - bearer:
            - transfers:create
      x-required-scope: transfers:create
      responses:
        '200':
          description: The transfer after the change
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /galleries:
    post:
      operationId: createGallery
      summary: >-
        Share a folder of photos as a gallery, free or paid (body: folder_id, title, price,
        currency, preview_mode, preview_count, watermark, client_name, client_email)
      description: >-
        Shares a folder of photos (the JPG, PNG and WebP files directly in it, up to 500) as a
        gallery at gallery_url (/g/...). Without price it is a free gallery (watermark optional).
        With price (0.01 to 99999.99, in currency: USD, EUR, GBP, CAD, AUD, CHF, SEK, NOK, DKK, PLN,
        CZK, NZD, SGD, HKD or MXN; USD by default) it is a paid gallery: visitors see watermarked
        previews (preview_mode all) or only the first preview_count photos (preview_mode first), pay
        with PayPal or card, whichever the workspace connected, and download the originals for 30
        days. pay_url (/pay/...) opens its checkout directly; after paying the buyer lands on the
        unlocked gallery and gets a receipt email with their download link. Getting paid needs Pro
        and PayPal or Stripe connected in Settings > Integrations; otherwise 403 with what to do.
        Creating it sends no email: client_email is kept for your own use. Needs transfers:create,
        and the token's creator must be allowed to create transfers.
      tags:
        - Galleries
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GalleryCreate'
      security:
        - bearer:
            - transfers:create
      x-required-scope: transfers:create
      responses:
        '201':
          description: The new gallery, with gallery_url and, when paid, pay_url
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gallery'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /galleries/{id}:
    get:
      operationId: getGallery
      summary: Get a gallery, its links and who paid
      description: >-
        Returns a gallery made with createGallery: gallery_url, pay_url (null when free), price,
        currency, preview settings, photo_count, and purchases (status completed or refunded,
        amount, currency, buyer_name, buyer_email, paid_at, access_until; never an access token).
        Only status completed means the buyer paid. Needs transfers:read.
      tags:
        - Galleries
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A gallery id, from createGallery's answer
          schema:
            type: string
            pattern: ^[0-9]{1,18}$
      security:
        - bearer:
            - transfers:read
      x-required-scope: transfers:read
      responses:
        '200':
          description: The gallery and its purchases
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gallery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /transfers/{id}/contacts:
    post:
      operationId: deliverTransferToContacts
      summary: Deliver a transfer to contacts' client portals
      description: >-
        Adds contacts of this workspace to a plain transfer's recipients, so it appears in their
        client portal. Sending ids that are already there changes nothing. No email is sent. A
        contact sees it only while their portal access is on (setContactPortalAccess). A view-only
        transfer shows its files in the portal without downloads until updateTransfer sets view_only
        false. A paid transfer is refused (409 conflict). Needs transfers:create; the token's
        creator must be allowed to share transfers and see contacts.
      tags:
        - Transfers
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A transfer id, from createTransfer's answer
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferContactsAdd'
      security:
        - bearer:
            - transfers:create
      x-required-scope: transfers:create
      responses:
        '200':
          description: Who the transfer is delivered to now
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferContacts'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /contacts:
    post:
      operationId: createContact
      summary: Add a contact
      description: >-
        Adds a contact (a workspace client) to this workspace, same as the app's "Add contact" form.
        Setting organization_name also creates or joins that organization. Never emails the contact
        or grants portal access on its own. Needs contacts:create.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      security:
        - bearer:
            - contacts:create
      x-required-scope: contacts:create
      responses:
        '201':
          description: The new contact
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    get:
      operationId: listContacts
      summary: List contacts
      description: >-
        Lists this workspace's contacts, newest first. query matches email, first name or last name.
        Needs contacts:read.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: query
          in: query
          required: false
          description: Search contacts by email, first or last name
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Max contacts to return (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
      security:
        - bearer:
            - contacts:read
      x-required-scope: contacts:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /contacts/{id}/portal-access:
    post:
      operationId: setContactPortalAccess
      summary: Turn client portal access on or off
      description: >-
        Turns portal access on or off for a contact. The first time it's turned on, Tarkle sends the
        invite email automatically. Needs contacts:portal.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A contact id, from createContact's or listContacts' answer
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactPortalAccessSet'
      security:
        - bearer:
            - contacts:portal
      x-required-scope: contacts:portal
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPortalAccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /contacts/{id}/portal-invite:
    post:
      operationId: resendContactPortalInvite
      summary: Resend a contact's portal sign-in email
      description: >-
        Emails a contact who already has portal access their sign-in link again. A contact whose
        portal access is off is refused (409 conflict): turn it on with setContactPortalAccess,
        which sends the first invite itself. The client portal is a Pro feature. Needs
        contacts:portal.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A contact id, from createContact's or listContacts' answer
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      security:
        - bearer:
            - contacts:portal
      x-required-scope: contacts:portal
      responses:
        '200':
          description: The sign-in email was sent
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPortalInvite'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
  /contacts/{id}/storage-limit:
    post:
      operationId: setContactStorageLimit
      summary: Set a contact's portal upload limit
      description: >-
        Sets how much one contact may upload from their client portal, in GB (1 to 10000; the
        default is 5 GB). Only the contact's own uploads count. No email is sent. Needs
        contacts:portal.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A contact id, from createContact's or listContacts' answer
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactStorageLimitSet'
      security:
        - bearer:
            - contacts:portal
      x-required-scope: contacts:portal
      responses:
        '200':
          description: The new limit
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactStorageLimitChanged'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    get:
      operationId: getContactStorageLimit
      summary: Read a contact's portal upload limit and use
      description: >-
        Returns a contact's portal upload limit and how much they have uploaded so far, in bytes.
        Needs contacts:read.
      tags:
        - Contacts
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: id
          in: path
          required: true
          description: A contact id, from createContact's or listContacts' answer
          schema:
            type: string
            format: uuid
      security:
        - bearer:
            - contacts:read
      x-required-scope: contacts:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactStorageLimit'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /file-requests:
    post:
      operationId: createFileRequest
      summary: Create a file request
      description: >-
        Creates a public upload link that collects files from anyone who opens it. Needs
        file_requests:create.
      tags:
        - File requests
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileRequestCreate'
      security:
        - bearer:
            - file_requests:create
      x-required-scope: file_requests:create
      responses:
        '201':
          description: The new file request
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
    get:
      operationId: listFileRequests
      summary: List file requests
      description: Lists this workspace's file requests, newest first. Needs file_requests:read.
      tags:
        - File requests
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: limit
          in: query
          required: false
          description: Max file requests to return (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
      security:
        - bearer:
            - file_requests:read
      x-required-scope: file_requests:read
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileRequestList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
  /teams:
    get:
      operationId: listTeams
      summary: List team folders
      description: >-
        Lists this workspace's team folders (not deleted), newest first, each with the id of its
        master folder so an agent can find where its files live. Storage use and membership stay in
        the app. There is no separate read scope: it needs teams:create, the scope the route checks.
      tags:
        - Teams
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
      security:
        - bearer:
            - teams:create
      x-required-scope: teams:create
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createTeam
      summary: Create a team folder
      description: >-
        Creates a team folder: a Pro-only shared folder with its own storage budget. Only an owner
        or admin of this workspace may create one. No members are assigned at creation -- add them
        through the app. A name already used in the workspace is 409 name_taken. Needs teams:create.
      tags:
        - Teams
      parameters:
        - name: X-Workspace-Key
          in: header
          required: true
          description: >-
            The 8-character key of the workspace this call acts on; GET /workspaces lists the keys a
            token can use. A workspace id is refused (400 workspace_key_required)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - name: workspace_key
          in: query
          description: >-
            The same key as the X-Workspace-Key header, for clients that cannot set headers. Send
            one of the two, or both with the same value (different values are 400
            conflicting_workspace)
          schema:
            type: string
            pattern: ^[a-z0-9]{8}$
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
      security:
        - bearer:
            - teams:create
      x-required-scope: teams:create
      responses:
        '201':
          description: The new team folder
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            RateLimit-Limit:
              $ref: '#/components/headers/IetfRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/IetfRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/IetfRateLimitReset'
            RateLimit-Policy:
              $ref: '#/components/headers/IetfRateLimitPolicy'
            X-RateLimit-Heavy-Limit:
              $ref: '#/components/headers/RateLimitHeavyLimit'
            X-RateLimit-Heavy-Remaining:
              $ref: '#/components/headers/RateLimitHeavyRemaining'
            X-Quota-Limit:
              $ref: '#/components/headers/QuotaLimit'
            X-Quota-Remaining:
              $ref: '#/components/headers/QuotaRemaining'
            X-Quota-Reset:
              $ref: '#/components/headers/QuotaReset'
            X-Quota-Warning:
              $ref: '#/components/headers/QuotaWarning'
            X-Tarkle-Api-Version:
              $ref: '#/components/headers/ApiVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/Unavailable'
        default:
          $ref: '#/components/responses/Problem'
```
