LinkHarbor API 概览

借助 REST API，你可以用自己的程序控制 LinkHarbor：创建页面和链接、编辑并发布草稿、生成短链接，或把统计数据拉进你自己的报表。本文面向开发者，介绍适用于所有端点的基本规则。

#哪种方式适合你？

#基础 URL 和版本

基础 URL

https://dock.at-harbor.com。所有产品端点都位于 /v1 下，例如 https://dock.at-harbor.com/v1/pages。

版本

目前只有 v1 这一个版本。版本号是路径的一部分。

协议

仅支持 HTTPS。

OpenAPI

机器可读的描述（OpenAPI 3.1）位于 https://dock.at-harbor.com/openapi.yaml。你可以把它导入 Postman、Insomnia 或代码生成器。

#在沙盒中测试

开发和测试可以使用单独的沙盒。它的行为与正式 API 相同，但两者完全分开：沙盒有自己的账户和自己的数据，任何内容都不会进入你真实的工作区。

API

https://drydock.at-harbor.com，路径与上面相同，例如 https://drydock.at-harbor.com/v1/pages。

控制台

https://sandbox-deck.linkharbor.com，例如用于创建 API 密钥。

页面

已发布的页面显示在 https://<handle>.sandbox.linkharbor.com。

账户

你真实的 LinkHarbor 账户在沙盒中无法使用。请另外创建一个沙盒账户。

沙盒不发送邮件。如果你通过 API 注册（POST /v1/auth/register），验证码会直接在响应的 _dev_verification 字段中返回。重置密码和更改邮箱也是如此。这个字段只存在于沙盒中，所以不要在代码中依赖它。

• 推送通知已关闭
• 付款通过 Stripe 的测试模式进行，不会产生真实的资金往来
• 速率限制约为正式值的三分之一，新账户限制为每个 IP 地址每小时 5 个
• 每月 1 日 3:00（UTC）沙盒会被完全清空，之后所有账户和数据都会消失
• 每个响应都带有响应头 X-Environment: sandbox

#身份验证简介

1. 以所有者或管理员身份，在控制台的“回调与 API”中创建一个带所需权限范围的 API 密钥（Creator Pro 起）
2. 通过 POST /v1/token 用密钥 ID 和密钥换取访问令牌
3. 每次请求都在请求头 Authorization: Bearer … 中发送令牌
4. 15 分钟后获取新的令牌

详细说明请参阅 API 密钥和访问令牌，权限说明请参阅权限范围。

#请求和响应

格式

请求和响应都是 UTF-8 编码的 JSON。文件上传还会使用 multipart/form-data。

Content-Type

每个带请求体的请求都要发送请求头 Content-Type: application/json。其他类型都会以 400 bad_request 被拒绝，包括缺少这个请求头时 curl 为 -d 自动设置的类型。

未知字段

端点不认识的字段会导致 422 validation_failed。响应中会列出这些未知字段。

损坏的 JSON

会导致 400 invalid_json。

大小

根据端点不同，请求体最多为 64 KB、1 MB 或 2 MB，文件上传最多 10 MB。超出时，API 返回 413 request_too_large。所有限额都列在速率限制中。

列表

以带 items 字段的对象返回，例如 {"items":[…]}。

创建

返回 HTTP 201 和新 ID，例如 {"id":123}。

没有返回值的操作

返回 {"ok":true}。

错误

始终采用固定格式，并带有机器可读的代码。参见 API 错误格式和错误代码。

#分页

没有统一的分页方式。大多数列表都很小，会完整返回；只有少数端点带有参数：

短链接的 sort 可取 created_desc、created_asc、redirects_desc 和 redirects_asc；q 会搜索 Slug、标题和目标网址（最多 100 个字符，不区分大小写）。统计端点的 period 可取 24h、7d、30d、90d、this_month、last_month、last_30d 和 custom；也可以改为传入 from 和 to。granularity 为 hour 或 day。

#请求 ID 和语言

• 每个响应都带有响应头 X-Request-Id，联系支持团队时请附上它
• 如果你自己发送 X-Request-Id 请求头，API 会使用它
• message 中的错误文本使用工作区所有者的账户语言，否则遵循 Accept-Language；error 中的代码始终不变

#从浏览器调用？

从技术上讲，API 允许从浏览器调用（CORS）。但密钥绝不能放进在访客一侧运行的代码中，无论是网站还是应用。请始终从你自己的服务器调用 API。

#套餐

各套餐都没有 API 调用次数配额，只受每分钟的速率限制约束。你套餐的内容限额（例如页面数、链接数或每个页面的模块数）在 API 中和在控制台中同样适用。参见套餐对比。

#第一次调用

# 用密钥换取令牌
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# 列出页面（权限范围 read:pages）
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

添加链接、修改设计并发布的完整示例，请参阅分步指南：通过 API 更新页面。