从 API 密钥到已发布的版本：添加链接、把它移到最前面、修改设计、验证草稿并发布，全部用 curl 和 jq 完成。

在这个示例中，你完全通过 API 更新一个现有页面：添加一个链接，把它移到最前面，修改按钮样式，验证草稿并发布。这些命令可以在任何装有 curl 和 jq 的 shell 中运行。

1. 创建 API 密钥

在控制台中打开“回调与 API”
点击“+ 创建新密钥”
为“页面”和“链接”都选择“写入”（其中包含读取权限）
点击“创建密钥”并复制密钥
从列表中复制密钥 ID

把这两个值保存为环境变量，不要写进脚本：

设置凭据

export LH_KEY_ID="6F668EA6598B0692"
export LH_KEY_SECRET="lt_…"
export API="https://dock.at-harbor.com"

2. 获取访问令牌

POST /v1/token

LH_TOKEN=$(curl -sS -X POST "$API/v1/token" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\":\"$LH_KEY_ID\",\"key_secret\":\"$LH_KEY_SECRET\"}" \
  | jq -r .token)

令牌的有效期为 15 分钟。如果你的脚本运行时间更长，请在中途重新获取。

3. 找到页面

GET /v1/pages

curl -sS "$API/v1/pages" -H "Authorization: Bearer $LH_TOKEN" \
  | jq '.items[] | {id, handle, title, status, current_version}'

记下页面的 id。在这个示例中是 42：

bash

PAGE_ID=42

4. 添加链接

POST /v1/pages/{id}/links

LINK_ID=$(curl -sS -X POST "$API/v1/pages/$PAGE_ID/links" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Autumn sale","target_url_template":"https://shop.example.com/autumn","enabled":true}' \
  | jq -r .id)
echo "New link: $LINK_ID"

API 返回 HTTP 201 和新 ID。新链接会排在列表末尾。如果达到套餐的链接上限，你会收到 409 link_limit_reached。

5. 把链接移到最前面

POST /v1/pages/{id}/links/reorder

curl -sS -X POST "$API/v1/pages/$PAGE_ID/links/reorder" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"order\":[$LINK_ID]}"

只需发送要移到最前面的 ID。其余链接会保持原有顺序，排在它们后面。

6. 在草稿中修改设计

执行 PATCH 时，theme_config 会被完整替换。所以请先读取草稿，只修改你想改的值，再把整个对象发回：

GET 和 PATCH /v1/pages/{id}/draft

THEME=$(curl -sS "$API/v1/pages/$PAGE_ID/draft" -H "Authorization: Bearer $LH_TOKEN" \
  | jq -c '(.theme_config // {}) | .button_style = "pill"')

curl -sS -X PATCH "$API/v1/pages/$PAGE_ID/draft" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"theme_config\":$THEME}"

button_style 可取 rounded、pill 和 square。theme_config 的其他字段包括 bg_color、text_color、button_color、button_text_color 和 background。

7. 验证草稿

GET /v1/pages/{id}/draft/validate

curl -sS "$API/v1/pages/$PAGE_ID/draft/validate" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"valid":true,"issues":[]}

如果 valid 为 false，issues 会列出问题。请在发布前修复它们。草稿与线上版本究竟有没有差异，可以通过 GET /v1/pages/$PAGE_ID 的 has_unpublished_changes 字段查看；如果它为 false，就可以跳过发布。

8. 发布

POST /v1/pages/{id}/publish

curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"version":8,"checksum":"…"}

现在访客会看到新版本，包括新链接、新顺序和新设计。如果你为 page.published 设置了 Webhook，它现在会收到一次投递。如果草稿无法发布，API 会返回 409 draft_not_publishable，并在 details.issues 中给出问题列表。

9. 撤销

如果你对结果不满意，可以把上一个版本载入草稿并重新发布：

恢复版本 7

curl -sS -X POST "$API/v1/pages/$PAGE_ID/versions/7/restore" -H "Authorization: Bearer $LH_TOKEN"
curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"

你也可以传入 current 代替版本号：这会丢弃上次发布以来草稿中的所有更改。恢复会还原设计、模板、自定义 CSS、SEO、模块和链接；标题、用户名和可见性不受版本管理。

常见错误

400 bad_request: 缺少 Content-Type: application/json 请求头。没有它，curl -d 会发送另一种类型。
401 invalid_token: 令牌在 15 分钟后已过期。请获取新令牌。
403 insufficient_scope: 密钥缺少某个权限范围，例如链接的“写入”。
设计突然被重置: theme_config 只带一个字段发送，替换了整个主题。请重新发送完整的主题，或使用 restore current 丢弃上次发布以来草稿中的所有更改。

所有错误代码的说明请参阅 API 错误格式和错误代码，所有端点请参阅按领域分类的 API 端点。

没找到答案？

告诉我们你需要什么，我们的客服团队会亲自帮你。

联系客服

分步指南：通过 API 更新页面

#1. 创建 API 密钥

#2. 获取访问令牌

#3. 找到页面

#4. 添加链接

#5. 把链接移到最前面

#6. 在草稿中修改设计

#7. 验证草稿

#8. 发布

#9. 撤销

#常见错误

你可能还想了解