---
title: "Transfers"
description: "Create a durable, shareable link from files or folders already in the library."
---

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

# Transfers

A transfer is a shareable link to one or more files or folders already in the workspace's library (upload
them first with [Uploads](/docs/api/uploads)). It is the same kind of link the app's own send flow creates: an
expiry, a password, one-time-download protection. This endpoint covers the plain case only -- video, audio
and canvas transfers, paid transfers and the "organization" recipient-email flow stay app-only for now.

| Method and path | Scope | What it does |
| --- | --- | --- |
| `POST /transfers` | `transfers:create` | Creates a transfer and returns its share link |
| `GET /transfers/{id}` | `transfers:read` | Reads one transfer's current status |
| `DELETE /transfers/{id}` | `transfers:create` | Ends a transfer early; the link stops working at once |

## Create a transfer

```bash
curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"id":"123","type":"file"}],"access":"public","title":"Q4 build"}' \
  https://tarkle.com/api/v1/transfers
```

```json
{
  "id": "2857",
  "url": "https://acme.tarkle.com/t/3QL4HIF9OTOP",
  "slug": "3QL4HIF9OTOP",
  "title": "Q4 build",
  "description": null,
  "access": "public",
  "expires_at": null,
  "burn_after_read": false,
  "view_only": false,
  "download_mode": "standard",
  "created_at": "2026-11-06T07:19:01.603729+00:00"
}
```

`url` is the real, working share link on the workspace's own custom domain when it has one, otherwise its
hosted address -- always `/t/{slug}`.

### Body

| Field | Required | Description |
| --- | --- | --- |
| `items` | Yes | `[{ id, type }]`, `type` is `"file"` or `"folder"`, `id` is a file id (digits, from `POST /uploads/.../complete`) or a folder id (uuid) |
| `access` | Yes | `"public"` or `"password"` |
| `password` | Only with `access: "password"` | The password needed to open the link |
| `title` | No | Shown on the share page |
| `description` | No | Shown on the share page |
| `expires_at` | No | ISO 8601, must be in the future. Omit for a link that never expires |
| `burn_after_read` | No | The link stops working after its first download. There is no numeric download-count limit today -- only this one-time form |
| `view_only` | No | Viewers can open files but not download them |
| `download_mode` | No | `"standard"` (default), `"email_required"` or `"direct"` |

## Read and end a transfer

```bash
curl -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" https://tarkle.com/api/v1/transfers/2857
curl -X DELETE -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" https://tarkle.com/api/v1/transfers/2857
```

`DELETE` answers `{ "deleted": true, "id": "2857" }`; the public link answers `404` immediately afterward.

## Plan limits

The same transfer-size and monthly-transfer-count limits the app applies: `413 transfer_too_large` when the
combined size of the selected items exceeds the plan's maximum transfer size, `429 transfer_monthly_limit`
when the workspace has reached its plan's monthly transfer count (Free: 15/month, Pro and above:
unlimited).

## From a CI pipeline

[`tarkleHQ/upload-action`](https://github.com/tarkleHQ/upload-action) wraps this endpoint for GitHub
Actions -- upload a build artifact and get a share link back in one step. See
[Automate with GitHub Actions](/docs/api/github-actions).

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