跳到内容
LinkdashLinkdash
简体中文
Esc
↑↓导航↵打开⌘J预览
本页内容

HTTP API

REST 接口位于 https://api.linkdash.dev/v1,使用控制台中创建的 bearer 密钥认证。支持的操作与 CLI 和 MCP 相同。

基础 URL:https://api.linkdash.dev/v1

认证:Authorization: Bearer ldash_...(在 控制台 → API 密钥 中创建密钥)。不要自行编造密钥。

CLI 参考:CLI。MCP:MCP。价格 / 配额:价格。服务发现(无需认证):GET https://api.linkdash.dev/v1。纯 Markdown 版本:api.md。

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

约定

  • 除非另有说明,均使用 JSON Content-Type: application/json。
  • 创建时,在 url、text 或 storageId(先调用 POST /uploads 获取)中只能选一个,或者传入 variants 数组(参见变体),或者传入 "kind": "folder" 并附带 name(参见文件夹)。生成上传地址的接口返回 { "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(参见访问与共享)。响应中的 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" }
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 链接

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 文件字节,然后在同一流程中创建链接:

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 上传:

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(布尔值)用于转发访问者的查询字符串,参见转发查询参数。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" }],记录抓取过该链接的爬虫和链接预览服务,它们永远不计入访问量;参见爬虫日志。

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 } 各状态的数量。

一次创建多个变体:

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 必填。键区分大小写,值按精确匹配比较。

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

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

转发查询参数

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

文件夹

文件夹是一种特殊的链接,用来列出你放进去的条目。其模型说明参见文件夹。

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"。文件夹和查看者的权限机制参见共享与访问。

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 和自定义域名。

这个页面有帮助吗?