本概览列出所有可以使用 API 密钥令牌调用的端点。所有路径都以 https://dock.at-harbor.com 开头。每个端点的具体字段请参阅 OpenAPI 描述：https://dock.at-harbor.com/openapi.yaml。
#身份验证和公开端点
| 方法和路径 | 身份验证 | 用途 |
|---|
| POST /v1/token | 无（密钥 ID 和密钥放在请求体中） | 用 API 密钥换取访问令牌 |
|---|
| GET /v1/plans | 无 | 套餐和价格 |
|---|
| GET /v1/pages/available?handle=… | 无 | 检查用户名是否可用 |
|---|
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/pages | read:pages | 工作区中的所有页面，含 ID、用户名、标题、状态、线上版本、可见性和网址 |
|---|
| POST /v1/pages | write:pages | 创建页面；必填：handle（2–64 个字符，字母、数字、连字符）和 template_key；可选：title、domain_id、theme_config |
|---|
| GET /v1/pages/{id} | read:pages | 单个页面；另含 has_unpublished_changes（草稿与已发布版本不同时为 true） |
|---|
| PATCH /v1/pages/{id} | write:pages | 更改 title、handle 或 discoverable（是否在目录中列出） |
|---|
| PATCH /v1/pages/{id}/visibility | write:pages | public、private 或 password（需带 password，4–72 个字符）；立即生效 |
|---|
| POST /v1/pages/{id}/publish | write:pages | 发布草稿；响应中包含新版本 |
|---|
| GET /v1/pages/{id}/versions | read:pages | 已发布的版本 |
|---|
| GET /v1/pages/{id}/versions/{version} | read:pages | 单个版本 |
|---|
| POST /v1/pages/{id}/versions/{version}/restore | write:pages | 把某个版本载入草稿；current 会丢弃草稿中的所有更改 |
|---|
| GET /v1/pages/{id}/seo | read:pages | SEO 和分享文本 |
|---|
| PATCH /v1/pages/{id}/seo | write:pages | seo_title、seo_description、og_title、og_description、og_image_asset_id、canonical_url、noindex |
|---|
| POST /v1/pages/{id}/invite-link | write:pages | 为已发布的私密页面创建邀请链接；days 为 1–30，默认 7。否则返回 409 page_not_private 或 page_not_published |
|---|
| POST /v1/pages/{id}/invite-link/revoke | write:pages | 撤销邀请链接 |
|---|
| POST /v1/pages/{id}/uploads | write:assets | 为页面上传文件 |
|---|
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/pages/{id}/draft | read:pages | 当前草稿：template_key、config、theme_config、custom_css、seo、图片分配和链接 |
|---|
| PATCH /v1/pages/{id}/draft | write:pages | 至少包含以下之一：config（作为 JSON 最多 64 KB，每段文本最多 5,000 个字符）、theme_config、custom_css（最多 50,000 个字符和 65,535 字节）、seo、template_key、template_asset_bindings |
|---|
| GET /v1/pages/{id}/draft/validate | read:pages | 检查草稿能否发布 |
|---|
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/pages/{id}/blocks | read:pages | 页面的模块 |
|---|
| POST /v1/pages/{id}/blocks | write:pages | 创建模块；必填：type 和 config |
|---|
| PATCH /v1/pages/{id}/blocks/{blockId} | write:pages | 编辑模块 |
|---|
| DELETE /v1/pages/{id}/blocks/{blockId} | write:pages | 删除模块 |
|---|
| POST /v1/pages/{id}/blocks/reorder | write:pages | 设置顺序 |
|---|
| GET /v1/blocks/schemas | read:pages | 所有模块类型及其 config 的结构定义 |
|---|
可以创建的类型：text、image、embed、spacer、social_links、form、integration、donation、modal、heading、notice、coupon、contact、opening_hours、tour、file、vcard、countdown 和 gallery。链接模块是固定的，不能通过这个端点创建。超出你套餐的模块类型会被 API 以 403 block_type_requires_plan 拒绝。模块的 config 作为 JSON 最多 128 KB，其中每段文本最多 10,000 个字符；信息弹窗中的 modal_body_html 最多可有 50,000 个字符，且不超过 65,535 字节。
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/pages/{id}/links | read:links | 页面的链接 |
|---|
| POST /v1/pages/{id}/links | write:links | 创建链接；必填：title（1–200）和 target_url_template（8–2048） |
|---|
| GET /v1/pages/{id}/links/{linkId} | read:links | 单个链接 |
|---|
| PATCH /v1/pages/{id}/links/{linkId} | write:links | 编辑链接 |
|---|
| DELETE /v1/pages/{id}/links/{linkId} | write:links | 删除链接 |
|---|
| POST /v1/pages/{id}/links/reorder | write:links | 设置顺序：{"order":[IDs]} |
|---|
创建和编辑时的可选字段：enabled、geo（国家规则，mode 为 allowlist 或 denylist，外加 countries）、device（按设备设置不同的目标）、starts_at 和 ends_at（定时）、protection_tier（机器人防护）以及 age_restriction。定时、国家和设备规则自 Creator Pro 起提供。调整顺序时，只需发送要移到最前面的 ID，其余链接会按原来的顺序跟在后面。不属于该页面的 ID 会被 API 以 422 validation_failed 拒绝，details.missing_link_ids 会列出它们。
#短链接
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/short-links | read:short_links | 短链接，支持 limit、offset、sort 和搜索参数 q；响应中包含 total |
|---|
| POST /v1/short-links | write:short_links | 创建；必填：target_url（http 或 https，8–2048）；可选：title（最多 120）和 custom_slug（3–32，小写字母、数字、连字符） |
|---|
| GET /v1/short-links/{id} | read:short_links | 单个短链接 |
|---|
| PATCH /v1/short-links/{id} | write:short_links | 更改 target_url 或 title |
|---|
| DELETE /v1/short-links/{id} | write:short_links | 删除短链接 |
|---|
如果达到套餐的短链接上限，API 会返回 402 plan_limit_reached。
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/assets | read:assets | 工作区的素材 |
|---|
| POST /v1/assets | write:assets | 上传文件（multipart/form-data，字段 file；可选：page_id、kind、title、alt_text） |
|---|
| DELETE /v1/assets/{assetId} | write:assets | 删除素材 |
|---|
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/forms | read:forms | 表单 |
|---|
| POST /v1/forms | write:forms | 创建表单；必填：name 和 fields（1–100 个字段） |
|---|
| GET /v1/forms/{id} | read:forms | 单个表单 |
|---|
| PATCH /v1/forms/{id} | write:forms | 编辑表单 |
|---|
| DELETE /v1/forms/{id} | write:forms | 删除表单 |
|---|
| GET /v1/forms/{id}/summary | read:forms | 摘要 |
|---|
| GET /v1/forms/{id}/submissions | read:forms | 提交记录，最新的在前（limit 1–500，默认 100；后续页通过 cursor = next_cursor 获取） |
|---|
| GET /v1/forms/{id}/submissions/export | read:forms | 所有提交记录导出为 CSV 文件，最新的在前，最多到套餐的导出上限（Creator Pro 起）；X-Export-Truncated 响应头表示是否被截断 |
|---|
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/stats/pages/{id}/summary | read:stats | 页面的关键指标 |
|---|
| GET /v1/stats/pages/{id}/timeseries | read:stats | 页面的时间序列 |
|---|
| GET /v1/stats/pages/{id}/compare | read:stats | 与上一时段对比 |
|---|
| GET /v1/stats/pages/{id}/links | read:stats | 每个链接的点击量 |
|---|
| GET /v1/stats/pages/{id}/widgets | read:stats | 小组件的点击量 |
|---|
| GET /v1/stats/pages/{id}/conversions/breakdown | read:stats | 页面的转化 |
|---|
| GET /v1/stats/workspaces/me/summary | read:stats | 所有页面的关键指标 |
|---|
| GET /v1/stats/workspaces/me/timeseries | read:stats | 所有页面的时间序列 |
|---|
| GET /v1/stats/workspaces/me/compare | read:stats | 与上一时段对比 |
|---|
| GET /v1/stats/workspaces/me/top-pages | read:stats | 热门页面 |
|---|
| GET /v1/stats/workspaces/me/conversions/breakdown | read:stats | 工作区的转化 |
|---|
| GET /v1/stats/workspaces/me/donations | read:donations | 支持者付款的合计 |
|---|
时段的选择方式见分页：使用 period，或使用 from 和 to。能回溯多久取决于套餐：Creator Pro 和 Agency 为 365 天，Enterprise 为 730 天。更早的时段会被截断到这个范围内。
#推送（只读）
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/push/history | read:stats | 推送历史（limit、offset） |
|---|
| GET /v1/push/usage | read:stats | 每周限额的用量 |
|---|
发送推送通知和管理推送规则只能在控制台中进行。
#工作区、模板和域名
| 方法和路径 | 权限范围 | 用途 |
|---|
| GET /v1/workspaces/me/entitlements | read:workspaces | 套餐功能和限额 |
|---|
| GET /v1/workspaces/me/usage | read:workspaces | 当前用量 |
|---|
| GET /v1/workspaces/me/usage/metering | read:workspaces | 用量历史 |
|---|
| GET /v1/workspaces/me/members | read:workspaces | 成员列表 |
|---|
| GET /v1/workspaces/me/settings | read:workspaces | 工作区设置 |
|---|
| GET /v1/workspaces/me/callback-secrets | read:workspaces | 回调密钥（不含明文密钥） |
|---|
| GET /v1/workspaces/me/callback-secrets/{id} | read:workspaces | 单个回调密钥（不含明文密钥） |
|---|
| GET /v1/templates | read:workspaces | 所有模板 |
|---|
| GET /v1/templates/available | read:workspaces | 内置模板和已启用的工作区模板，含有效的 template_key 值；工作区模板的键为 ws:<key>，type 为 workspace |
|---|
| GET /v1/templates/{key} | read:workspaces | 单个模板 |
|---|
| GET /v1/workspaces/me/templates | read:workspaces | 你自己的工作区模板 |
|---|
| GET /v1/workspaces/me/templates/{id} | read:workspaces | 单个工作区模板 |
|---|
| POST, PATCH, DELETE /v1/workspaces/me/templates[/{id}] | write:templates | 创建、编辑、删除工作区模板；html 最多 60,000 字节（否则返回 422 validation_failed，details.reason 为 maxBytes），最多 32 个 asset_slots |
|---|
| GET /v1/domains | read:workspaces | 自定义域名 |
|---|
| GET /v1/domains/available | read:workspaces | 可用于页面的域名 |
|---|
#API 密钥无法使用的功能
Webhook、集成、发送推送通知、管理域名、成员、账单和删除页面都只能在控制台中使用。回调密钥也只能在控制台中创建和管理；用 read:workspaces 只能列出和读取它们（不含明文密钥）。完整列表请参阅权限范围详解。传入的数据（销售和你自己的实时数据）需要用单独的密钥发送到回调中介绍的端点。
