---
title: HTTP API
description: >-
  REST 接口位于 https://api.linkdash.dev/v1，使用控制台中创建的 bearer 密钥认证。支持的操作与 CLI 和 MCP
  相同。
sidebar:
  label: HTTP API
  order: 4
---
基础 URL：`https://api.linkdash.dev/v1`

认证：`Authorization: Bearer ldash_...`（在 [控制台 → API 密钥](https://linkdash.dev/dashboard/keys) 中创建密钥）。不要自行编造密钥。

CLI 参考：[CLI](/zh/cli)。MCP：[MCP](/zh/mcp)。价格 / 配额：[价格](/zh/pricing)。服务发现（无需认证）：`GET https://api.linkdash.dev/v1`。纯 Markdown 版本：[api.md](https://linkdash.dev/api.md)。

公开 ID 是 slug（`deck`、`k3m9xq`），而不是 Convex 的 `_id`。JSON 字段名与 CLI 标准输出一致（`id`、`url`、`kind`……）。

## 约定

- 除非另有说明，均使用 JSON `Content-Type: application/json`。
- 创建时，在 `url`、`text` 或 `storageId`（先调用 `POST /uploads` 获取）中只能选一个，**或者**传入 `variants` 数组（参见[变体](#variants)），**或者**传入 `"kind": "folder"` 并附带 `name`（参见[文件夹](#folders)）。生成上传地址的接口返回 `{ "uploadUrl", "storageId" }`，宿主环境再将文件字节 PUT 到 `uploadUrl`。小文件仍可在 `POST /links` 上通过 multipart 的 `file` 字段上传。
- 时长：`7d`、`24h`、`30m`、`1w` 或 ISO 日期。对应字段：`expires` / `expiresAt`、`starts` / `startsAt`。
- 打开次数限制：可选的正整数 `maxOpenings`。成功打开达到该次数后，链接会暂停。调高 `maxOpenings` 或使用 `clearMaxOpenings` 即可恢复访问。省略 `maxOpenings` 表示不限次数。
- 如果同一个 slug 同时存在于所有者的两个域名上，请传入 `?domain=` 或 JSON 字段 `domain`。
- 错误：返回 `{ "error": "..." }`，可能附带 `code`。如果 `lida.sh` 上的 slug 已被占用，返回 `409`，且 `code: "slug_taken"`。
- 访问权限：新建的链接和文件夹默认为 `restricted`，除非请求体中设置了 `access`（参见[访问与共享](#access-and-sharing)）。响应中的 `url` 是共享 URL（`https://linkdash.dev/s/<token>`）；如果链接是公开的，则返回短链接。
- 写操作计入每月事件配额（共享、取消共享和重置也算在内）。列表、获取、统计、导出、共享列表、“与我共享”列表，以及 webhook 列表和获取不计入。访问、下载和播放数据的采集仍然计入。

## 端点

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links` (`?q=&tag=&kind=&status=&folder=&limit=&cursor=`) | `links_list` |
| `links get <id>` | `GET /links/:id` (`?domain=`) | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id` (`?contents=keep\|delete`) | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares`（不带 id） | `PATCH /links/:id/shares/:email` | `{ "role": "viewer" \| "editor" }` | `{ "id", "email", "role" }` |
| `POST /links/:id/unlock` | `{ "variant"?, "password"?, "variantPassword"? }` | `{ "_id", "variant", "unlocked": true, "minutes": 30, ...target }` |
| `GET /links/:id/activity` | — | `{ "items": [{ "_id", "_creationTime", "action", "detail"?, "actor" }], "cursor" }` |
| `GET /shares` | `links_shares`（不带 `id`） |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update` (`resetShareLink: true`) |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| （生成上传地址后由宿主环境 PUT） | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`, `GET/DELETE /webhooks/:id`, `POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`, `GET /domains/:host/connect`, `POST /domains/:host/verify`, `DELETE /domains/:host` | `domains_*` |

`auth create`、`auth login` 和 `auth logout` 是浏览器设备授权流程，不是 Unkey 路由。

## `GET /me`

返回当前登录的账户：`{ "userId": "...", "email": "...", "name": "..." }`。邮箱和名称未知时会省略。

## 创建 URL 链接

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","slug":"welcome","access":"public"}'
```

JSON 请求体在 `url`、`text` 或 `storageId` 中只能选一个。此外还可以传入以下可选字段：`access`（默认 `restricted` \| `link` \| `public`）、`slug`、`name`、`tags`、`starts`、`expires`、`maxOpenings`、`password`、`domain`、`previewName`、`previewDescription`、`previewImageStorageId`、`sticky`、`forwardParams`、`utm`（仅限 URL 链接），以及用于在文件夹内创建链接的 `folder`（+ `folderDomain`）。简写形式会创建一个名为 `main` 的变体；顶层的 `password`、`starts`、`expires` 和 `maxOpenings` 作为链接级门控。响应：`{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`。

`GET /links` 每次返回一页结果 `{ "items": [...], "cursor" }`。`?limit=` 取值 1-100（默认 50）；把上一页返回的值作为 `?cursor=` 传入，直到它为 `null`。`q` 按完整单词匹配（最后一个词按前缀匹配），结果按相关性排序。每个条目为 `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }`（文件夹行额外包含 `items`）。`kind` 筛选额外支持 `folder` 和 `group`，`status` 筛选额外支持 `mixed`；`folder=<slug>|root`（+ `folderDomain`）用于列出某个文件夹或顶层的内容。`GET /links/:id` 返回包含 `access` 和 `variants` 的完整链接；内容（`destinationUrl` / `textContent` / `fileName`）保存在各个变体上。

## 上传文件

先生成上传 URL（`{uploadUrl,storageId}`），再从宿主环境 PUT 文件字节，然后在同一流程中创建链接：

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: application/pdf" --data-binary @./deck.pdf "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"deck.pdf","fileType":"application/pdf","fileSize":12345}'
```

小文件仍可在 `POST /links` 上使用 multipart 上传：

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

可选的 multipart 字段：`access`、`slug`、`name`、`tags`、`starts` / `startsAt`、`password`、`expires`、`maxOpenings`、`domain`、`previewName`、`previewDescription`、`previewImage`。

## 更新、统计与 CSV

`PATCH /links/:id` 支持 JSON 或 multipart。替换文件内容有两种方式：先调用 `POST /uploads` 并由宿主环境 PUT 文件，再传入 `storageId`；或者使用 multipart 字段 `file`（仅限单变体链接）。`--status` / `{ "status": "expired" }` 会被拒绝，请改用 `expires`。`{ "status": "scheduled" }` 也会被拒绝，请改用 `starts`。可选的 `maxOpenings` 会在打开次数达到上限后暂停链接；`clearMaxOpenings` 用于移除该限制。`sticky`（布尔值）和 `restartSplit`（布尔值）控制变体分配；`forwardParams`（布尔值）用于转发访问者的查询字符串，参见[转发查询参数](#forward-query-parameters)。`access` 决定谁可以打开链接；`resetShareLink: true` 会签发新的共享 URL。响应：`{ "id", "url", "access", "status", "variantStatuses" }`。

`GET /links/:id/stats?last=24h` 返回 `visits`、`downloads`、`plays`、`visitsInLast`、`countries`、`referrers`、`variants`（各变体的汇总）、`visitors` 和 `crawlers`。其中 `crawlers` 的格式为 `[{ "crawler", "company", "category", "hits", "lastSeen" }]`，记录抓取过该链接的爬虫和链接预览服务，它们永远不计入访问量；参见[爬虫日志](https://linkdash.dev/pricing.md)。

`GET /links/export` 返回 CSV，列为 `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`，每个变体占一行（`folder` 是所在文件夹的 slug；`access` 为 `restricted`、`link` 或 `public`）。`POST /links/import` 接受原始 CSV 或 multipart `file`。各行按 slug + 域名分组：第一行创建链接及其变体，后续行添加变体；对于已有链接，先更新字段，再按名称更新或添加变体。`kind` 为 `folder` 的行（需带 `name`）会创建文件夹；`folder` 列会在所有行都处理完后，再把链接放入对应文件夹。`access` 为空时，新链接设为受限（restricted），已有链接保持不变。

对文件夹调用 `DELETE /links/:id` 时，可以传 `?contents=keep`（默认：其中的条目上移一级）或 `?contents=delete`（其中的条目和子文件夹一并删除）。

## 变体

每个链接都是一个容器，包含一个或多个**变体**。每个变体包括：内容（`url` | `file` | `text`）、自己的门控（`password`、`paused`、`starts`、`expires`、`maxOpenings`）、一个 `weight`，以及可选的访问者条件 `when`。链接本身持有 slug、域名、名称、标签、预览、自己的门控（优先于变体门控）、`sticky`（默认 `true`）和 `splitVersion`（调用 `restartSplit` 时递增）。不传 `variants` 时，链接只有一个名为 `main` 的变体。变体名称只能包含小写字母、数字和中间的连字符，长度为 1–40 个字符，同一链接内不能重复。每个链接最多 20 个变体。

每位访问者只会分到一个变体。`when` 条件匹配的变体组成候选池（如果都不匹配，则使用无条件变体），再从中按权重选取：启用 sticky 时，根据访问者 + 链接 + `splitVersion` 的哈希固定选取，否则随机选取。爬虫获得第一个处于生效状态的无条件变体。包含多个变体的链接，其 `kind` 为 `group`。链接的 `status` 取值规则：设置了链接门控时取链接门控的状态；否则取所有变体共同的状态；如果各变体状态不一致，则为 `mixed`。`variantStatuses` 统计 `{ active, paused, expired, scheduled }` 各状态的数量。

一次创建多个变体：

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"promo","variants":[{"name":"a","url":"https://example.com/a"},{"name":"b","url":"https://example.com/b","weight":3,"when":{"countries":["DE","AT"]}}]}'
```

每个变体包含：`name`（必填）；`url` | `text` | `storageId`（+ `fileName`、`fileType`、`fileSize`）三选一；以及 `password`、`starts`、`expires`、`maxOpenings`、`utm`、`weight`、`when`。multipart 创建仅支持简写形式。

| 路由 | 请求体 | 响应 |
| --- | --- | --- |
| `GET /links/:id/variants` | — | 变体数组 |
| `POST /links/:id/variants` | JSON 或 multipart `file`：`name`（必填）、内容、`password`、`starts`、`expires`、`maxOpenings`、`utm`、`weight`、`when` | 该变体 |
| `PATCH /links/:id/variants/:name` | `name`（重命名）、`url`、`text`、`storageId` / `file`、`password`、`clearPassword`、`starts`、`clearStarts`、`expires`、`clearExpires`、`maxOpenings`、`clearMaxOpenings`、`status`（`active` \| `paused`）、`weight`、`when`、`clearWhen`、`utm` | 该变体 |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }`（最后一个变体不能删除） |

`when` 的键（值均为字符串数组；已设置的每个键都必须匹配）：`countries`（ISO-2）、`devices`（`mobile` | `tablet` | `desktop`）、`os`（`windows` | `macos` | `android` | `ios` | `linux` | `other`）、`browsers`（`edge` | `chrome` | `firefox` | `safari` | `other`）、`languages`（前缀匹配）、`referrerHosts`（主机名后缀匹配）。

### 查询参数规则

`when.params` 是一个规则数组，最多 10 条，作用于访问者的查询字符串（如 `lida.sh/promo?src=newsletter`）；所有规则都必须满足。每条规则的格式为 `{ "key", "op", "value" }`，`op` 可选 `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in`（此时 `value` 是以 `|` 或逗号分隔的列表）| `exists` | `missing`。除 `exists` / `missing` 外，`value` 必填。键区分大小写，值按精确匹配比较。

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

参数值在链接被打开时进行匹配，不会存入分析数据。

### 转发查询参数

`forwardParams` 是链接上的布尔值，默认为 `false`。它可以在 `POST /links` 和 `PATCH /links/:id` 中设置，并由 `GET /links/:id` 返回。启用后，访问者的完整查询字符串会追加到 URL 变体上。访问者传入的值会覆盖已存储的值，`utm` 也不例外。文件和文本变体会忽略此设置。这是路由功能，不是访问控制：任何人都可以添加参数。参数值不会存入分析数据。

## 文件夹

文件夹是一种特殊的链接，用来列出你放进去的条目。其模型说明参见[文件夹](/zh/folders)。

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"folder","name":"Q4 launch","slug":"q4"}'

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/deck","folder":"q4"}'

curl https://api.linkdash.dev/v1/links/k3m9xq/move \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"folder":"q4"}'

curl "https://api.linkdash.dev/v1/links?folder=q4" -H "Authorization: Bearer ldash_..."
```

| 路由 | 请求体 | 响应 |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` 加上常规链接字段；不能包含 `url`、`text`、`storageId` 或 `variants` | 新建的文件夹 |
| `POST /links/:id/move` | `{ "folder": "<slug>" }`，或用 `{ "folder": null }` 移到顶层；可选 `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }`（访问权限不变，生成新的共享 URL，不保留共享成员） |

移动和复制各计为一个事件。文件夹 slug 不存在时返回 `404`（`Folder "<slug>" not found`）；如果 slug 对应的不是文件夹，或者试图把文件夹移入自身或其下级文件夹，返回 `400`。文件夹最多嵌套 32 层。

## 访问与共享

每个链接和文件夹都有 `access` 属性，可选值如下：`restricted`（默认；仅所有者和被共享者登录后可通过 `https://linkdash.dev/s/<token>` 访问）、`link`（持有该 URL 的任何人均可访问）和 `public`（任何人均可通过短链接访问）。可在 `POST /links` 或 `PATCH /links/:id` 中设置。需要公开发布的链接请传入 `"access": "public"`。文件夹和查看者的权限机制参见[共享与访问](/zh/sharing)。

```bash
curl https://api.linkdash.dev/v1/links/q4/shares \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["anna@example.com","ben@example.com"]}'

curl https://api.linkdash.dev/v1/links/q4/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/links/q4/shares/ben%40example.com -H "Authorization: Bearer ldash_..."

curl -X POST https://api.linkdash.dev/v1/links/q4/reset-link -H "Authorization: Bearer ldash_..."

curl https://api.linkdash.dev/v1/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/shared/<_id> -H "Authorization: Bearer ldash_..."
```

| 路由 | 请求体 | 响应 |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }`（1–50 个邮箱） | `{ "id", "url", "access", "invited", "alreadyShared" }` |
| `DELETE /links/:id/shares/:email` | — | `{ "id", "email", "removed": true }` |
| `GET /links/:id/shares` | — | `[{ "email", "role": "viewer", "accepted", "invitedAt", "viaFolder"?: { "id", "name"?, "slug" } }]` |
| `GET /shares` | — | `{ "items": [{ "id", "name"?, "kind", "access", "url", "people": [{ "email", "accepted", "invitedAt" }] }], "cursor" }`（你共享出去的所有内容） |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }`（`:id` 是 `GET /shared` 返回的 `_id` 或共享令牌） |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

在 `POST /links/:id/shares` 中传入 `"role": "editor"` 可添加编辑者。编辑者可以修改条目，也能查看统计和活动记录；但无法查看或修改密码、slug、域名、访问权限和共享设置，也不能删除、移动或复制条目（返回 `403`）。编辑者使用条目的 `_id` 或共享令牌作为 `:id`。受密码保护的变体对编辑者保持 `locked: true`，直到调用 `POST /links/:id/unlock` 解锁（解锁有效期 30 分钟；每小时最多允许十次密码错误，超出后返回 `429`）。他人保存后再次保存时，只有请求中带了 `expectedVersion` 才会返回 `409`。slug 重复时，所有共享路由都接受 `?domain=`。在对应邮箱拥有已验证账户之前，`accepted` 为 `false`；出现 `viaFolder` 表示访问权限继承自上级文件夹。每个条目最多共享给 200 人，每个账户每天最多发送 100 封邀请邮件。`GET /shares` 和 `GET /shared` 每次返回一页：`?limit=` 取值 1-100（默认 50）；把上一页返回的值作为 `?cursor=` 传入，直到 `cursor` 为 `null`。共享、取消共享和重置各计为一个事件，退出共享不计入。即使退出共享，通过上级共享文件夹获得的访问权限仍会保留。

## 错误

| 状态码 | 场景 |
| --- | --- |
| 400 | 校验失败、缺少请求体、混用多种创建方式 |
| 401 | 缺少 bearer 密钥或密钥无效 |
| 404 | slug、域名或文件夹不存在 |
| 409 | slug 已被占用（`code: "slug_taken"`） |
| 429 | 已达到每月事件配额 |
| 503 | 当前部署未配置 API 密钥 |

相关端点参见 [webhooks](/zh/webhooks) 和[自定义域名](/zh/domains)。
