自动化 REST API

自动化 OrbitPage,无需共享仪表板会话。

创建范围令牌并从脚本、n8n、后端或 CI 端到端管理 OrbitPage 仪表板。

最新修订:2026年8月4日

使用受限个人令牌管理 OrbitPage 工作区:编辑和发布页面,并使用媒体、域名、分析、AI、Shop、新闻通讯和账单功能。

API v1https://orbitpage.com/api/v1HTTPS · JSON · UTF-8
  1. 01个人令牌
  2. 02修订检查
  3. 03验证并发布
API 边界

三个凭证边界涵盖三个不同的工作。

此页面记录了版本化的 REST 边界。 OrbitPage 令牌不是 OpenAI 提供商密钥,并且从不验证私有仪表板端点。

表面凭证目的和支持
自动化 REST APIop_pat_...支持脚本、n8n、服务器后端和 CI 的外部 API。它通过 /api/v1 管理令牌绑定的工作区。
OrbitPage AIop_pat_... + ai:read/ai:write公共计划/提交流程准备并应用经过验证的人工智能提案。任何 OpenAI 提供商凭证仍然是一个单独的服务器端问题,并且永远不是 OrbitPage 不记名令牌。
仪表板 APISaaS 上的 Firebase 会话; OSS 上的管理会话私有浏览器到应用程序的路由。它们不是稳定的外部集成合约,不得接收个人 API 代币。
合同

版本化资源涵盖仪表板;链接端点显示安全更新循环。

每个请求都绑定到创建令牌时选择的工作区。令牌无法在 URL 或请求正文中选择其他租户,并且每次调用时都会再次检查当前工作区权限。

该合约使用标准 HTTPS JSON 操作——GET、POST、PUT、PATCH 和 DELETE——并支持curl、n8n 的 HTTP 请求节点和生成的 OpenAPI 客户端。

01
GET/api/v1/links

读取每个页块

返回有序集合、工作区标识和当前修订。

范围: links:read
02
PATCH/api/v1/links/{linkId}

更改一个现有块

合并可编辑字段,验证整个页面并发布新修订版。

范围: links:write
03
PUT/api/v1/links

替换完整集合

使用它在读取和保留当前集合后添加、删除或重新排序块。

范围: links:write
仪表板表面API 路径范围
工作区和完整草稿/workspace · /draftworkspace:read
简介、主题和子页面/profile · /theme · /pagesprofile:* · theme:* · pages:*
一般、隐私和菜单设置/settings/*settings:*
发布、版本和备份/publication · /versions · /backuppublication:* · backup:*
媒体和自定义域/media/* · /domains/*media:* · domains:*
分析和审查人工智能变化/analytics · /ai/*analytics:read · ai:*
商店和时事通讯/shop/* · /newsletter/*shop:* · newsletter:*
团队和计费/team/* · /billing/*team:* · billing:*
开放OpenAPI 3.1规范
API v1 · 65 操作

每个支持的仪表板操作,按其控制的表面分组。

以下路径以 https://orbitpage.com/api/v1 为基准。方法、路径和权限范围是稳定的集成契约;请求架构、格式、枚举值和响应模型位于链接的 OpenAPI 3.1 文档中。未知路由返回 404,不支持的方法绝不会被静默转换。

01
工作空间、内容和外观检查令牌绑定工作区并管理其完整的草稿、配置文件、块、主题和子页面。
11 操作
方法和路径操作所需范围输入和控制
GET/workspace阅读工作空间、计划、访问、使用和修订workspace:read
GET/draft阅读完整的可编辑页面草稿workspace:read
GET/links列出页面块和当前版本links:read
PUT/links替换完整的有序块集合links:writeLinksReplaceRequest · If-Match
PATCH/links/{linkId}更新一个块上的可编辑字段links:writeLinkPatch · If-Match
GET/profile读取个人资料身份和元数据profile:read
PATCH/profile更新个人资料字段profile:writeJSON · If-Match · ?publish=1
GET/theme阅读活动草稿主题theme:read
PUT/theme替换草稿主题theme:writeJSON · If-Match · ?publish=1
GET/pages列出配置的子页面pages:read
PUT/pages替换配置的子页面pages:writearray | { pages } · If-Match · ?publish=1
02
设置和发布控制菜单、隐私、托管公共文件、站点地图生成和明确的草稿公开生命周期。
9 操作
方法和路径操作所需范围输入和控制
GET/settings读取菜单、隐私、文本文件和站点地图设置settings:read
PUT/settings/menu更新菜单设置settings:writeJSON · If-Match · ?publish=1
PUT/settings/privacy更新同意和隐私设置settings:writeJSON · If-Match · ?publish=1
POST/settings/text-files创建托管公共文本文件settings:writeTextFileCreateRequest · If-Match
PUT/settings/text-files/{key}更新托管公共文本文件settings:writeTextFileUpdateRequest · If-Match
DELETE/settings/text-files/{key}删除托管公共文本文件settings:writeIf-Match
POST/settings/sitemap重新生成托管站点地图settings:writeIf-Match
GET/publication阅读草稿和发布状态publication:read
POST/publication发布最新的经过验证的草稿publication:write
03
版本、备份和媒体恢复修订内容、导出或导入工作区数据以及运行保留-上传-最终确定媒体生命周期。
9 操作
方法和路径操作所需范围输入和控制
GET/versions列出可恢复的已发布页面版本backup:read
POST/versions/{revision}/restore恢复并立即发布历史版本backup:writeIf-Match
GET/backup导出托管工作区备份backup:read?sections=profile,links,…
POST/backup/restore验证、恢复并立即发布托管备份backup:writeBackupRestoreRequest · If-Match
GET/media列出工作区媒体元数据和使用情况media:read
POST/media/cleanup预览或删除未引用的媒体media:writeMediaCleanupRequest
POST/media/uploads/reserve保留直接媒体上传media:writeMediaUploadReserveRequest
POST/media/uploads/finalize最终确定并注册上传的对象media:writeUploadTokenRequest
DELETE/media/uploads中止保留的媒体上传media:writeUploadTokenRequest
04
领域、分析和人工智能管理 DNS 激活、读取计划范围内的性能报告并仅在经过验证的预览后应用 AI 更改。
8 操作
方法和路径操作所需范围输入和控制
GET/domains读取域状态和 DNS 要求domains:read
POST/domains连接自定义域domains:writeDomainConnectRequest
POST/domains/refresh刷新验证并激活domains:write
DELETE/domains断开自定义域domains:write
GET/analytics阅读仪表板分析报告analytics:read?days=7|30|90
GET/ai/allowance读取AI限额和当前使用情况ai:read
POST/ai/plan生成经过验证的 AI 更改预览ai:writeAiPlanRequest
POST/ai/commit提交之前验证的 AI 预览ai:writeAiCommitRequest
05
Shop连接商务、管理产品和外观、上传受保护的文件,然后发布或取消发布同步的商店块。
10 操作
方法和路径操作所需范围输入和控制
GET/shop读取产品、订单、客户和 Shop 状态;该操作可能初始化 Shop 私有数据并刷新 Stripe 状态shop:read?refresh=0|1
POST/shop/connect创建或继续 Stripe Connect 入门shop:write
POST/shop/products创建或更新商店产品shop:writeShopProductRequest
DELETE/shop/products/{productId}删除商店产品shop:write
PUT/shop/appearance替换整个商店外观shop:writeShopAppearanceRequest
POST/shop/publish发布 Shop 及其同步页面区块shop:write
POST/shop/unpublish取消发布商店shop:write
POST/shop/uploads/reserve保留产品文件上传shop:writeShopFileUploadReserveRequest
POST/shop/uploads/finalize完成产品文件上传shop:writeShopUploadTokenRequest
DELETE/shop/uploads取消已预留的产品文件上传shop:writeShopUploadTokenRequest
06
时事通讯配置加密 SMTP 传送、管理同意的订阅者并控制整个活动生命周期。
9 操作
方法和路径操作所需范围输入和控制
GET/newsletter读取订阅者、活动和 SMTP 状态newsletter:read
PUT/newsletter/settings更新加密的 SMTP 设置newsletter:writeNewsletterSmtpRequest
POST/newsletter/settings/test发送配置测试newsletter:writeEmailRecipientRequest
POST/newsletter/subscribers添加或更新同意的订户newsletter:writeNewsletterSubscriberRequest
DELETE/newsletter/subscribers/{subscriberId}删除订阅者newsletter:write
POST/newsletter/campaigns创建或更新营销活动newsletter:writeNewsletterCampaignRequest
DELETE/newsletter/campaigns/{campaignId}删除营销活动newsletter:write
POST/newsletter/campaigns/{campaignId}/send排队或安排活动newsletter:writeNewsletterSendRequest
DELETE/newsletter/campaigns/{campaignId}/send取消排队的活动newsletter:write
07
团队和计费管理协作者和邀请、检查订阅并打开经过身份验证的 Stripe 结帐或门户会话。
9 操作
方法和路径操作所需范围输入和控制
GET/team列出成员和待处理的邀请team:read
POST/team/invitations创建工作区邀请链接而不发送电子邮件team:writeTeamInvitationRequest
PATCH/team/members/{memberUid}更新成员角色team:writeTeamRoleRequest
DELETE/team/members/{memberUid}删除工作区成员team:write
DELETE/team/invitations/{invitationId}撤销待处理的邀请team:write
GET/billing读取计划和订阅状态billing:read
POST/billing/checkout创建 Stripe 计划结账billing:writeBillingCheckoutRequest
POST/billing/portal创建 Stripe 计费门户会话billing:writeBillingPortalRequest
POST/billing/promotion-code兑换促销代码并重新核对套餐权益billing:writePromotionCodeRedeemRequest
打开完整的OpenAPI 3.1合约
身份验证

为一种自动化和一种环境创建一种令牌。

打开仪表板 > 帐户 > 个人 API 令牌。为令牌指定一个可识别其所有者和用途的名称,选择完整工作区、只读工作区、仅链接或单个资源范围,然后选择 30、90 或 365 天的到期日,或者在记录的轮换过程已存在时选择无到期日。

01

确认您的身份

令牌创建是一项敏感帐户操作,需要最近的 Google 或密码身份验证。

02

选择最小范围

每个资源的读取和写入范围是分开的 - 例如 theme:read, theme:write, shop:read shop:write. 写入范围自动包含其匹配的读取范围。

03

复制密码一次

OrbitPage 存储 SHA-256 哈希值,而不是可恢复的机密。如果丢失,则撤销它并创建另一个令牌。

04

将其存储在代码之外

使用环境变量或 CI 秘密存储。切勿将令牌放入 URL、存储库、屏幕截图、浏览器捆绑包或构建日志中。

macOS / Linuxbash
export ORBITPAGE_TOKEN='op_pat_...'

curl --silent --show-error --include \
  --header "Authorization: Bearer $ORBITPAGE_TOKEN" \
  https://orbitpage.com/api/v1/links
WindowsPowerShell
$env:ORBITPAGE_TOKEN = 'op_pat_...'
$headers = @{ Authorization = "Bearer $env:ORBITPAGE_TOKEN" }

Invoke-RestMethod -Uri 'https://orbitpage.com/api/v1/links' -Headers $headers
GET /links

在每次更改之前阅读集合并捕获其修订版本。

响应正文包含数据中的有序块和当前数字修订版。相同的修订版出现在 X-OrbitPage-Revision 中并作为弱 ETag。保存 If-Match 的任一值;不要在不相关的运行中猜测或缓存它。

响应示例HTTP + JSON
HTTP/2 200
etag: W/"42"
x-orbitpage-revision: 42
content-type: application/json; charset=utf-8

{
  "object": "list",
  "data": [
    {
      "id": "portfolio-main",
      "type": "link",
      "title": "Selected work",
      "description": "Recent projects and case studies",
      "url": "https://example.com/work",
      "isActive": true,
      "status": "live",
      "availability": "available",
      "clickCount": 18,
      "position": 0
    }
  ],
  "revision": 42,
  "workspace": {
    "tenantId": "tenant_...",
    "pageId": "page_...",
    "username": "your-page"
  }
}
data完整的有序块集合。数组顺序是视觉页面顺序。
revision每次写入使用的乐观并发版本。
workspace永久绑定到此令牌的租户、页面和用户名。
ETag作为下一个 If-Match 标头直接传递的最安全值。
PATCH /links/{linkId}

使用 PATCH 对现有块进行最小的更改。

对 GET 返回的 ID 进行 URL 编码,并仅发送应更改的字段。 OrbitPage 将补丁合并到现有块中,保护身份和分析字段,根据其架构和计划验证完整页面,然后立即发布。

更新一个区块curl
curl --request PATCH \
  --url https://orbitpage.com/api/v1/links/portfolio-main \
  --header "Authorization: Bearer $ORBITPAGE_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'If-Match: W/"42"' \
  --data '{
    "title": "Book a consultation",
    "url": "https://example.com/book",
    "isActive": true
  }'
字段组示例行为
内容title, description, url, content, textItems对现有块类型有效时可编辑。
可见性和时间安排isActive, status, availability, startDate, endDate, timezone与调度和计划规则一起验证。
外观和媒体icon, coverImage, backgroundColor, alignment, size仅当值与页面架构匹配时才接受。
受保护id, type, clickCount, ctaClicks, systemKey被忽略或拒绝。系统管理的块无法修补。
PUT /links

仅当集合本身必须更改时才使用 PUT。

PUT 替换完整的有序集合。它是添加块、删除块或更改页顺序的操作。它不是更新一个标题的快捷方式:省略一个块会将其从页面中删除。

01GET读取每个块和 ETag
02本地修改保留 ID 和未触及的块
03PUT + If-Match验证并发布
安全读取-修改-写入脚本Node.js 22+
const token = process.env.ORBITPAGE_TOKEN;
if (!token) throw new Error("ORBITPAGE_TOKEN is missing");

const endpoint = "https://orbitpage.com/api/v1/links";
const authorization = { Authorization: `Bearer ${token}` };

const read = await fetch(endpoint, { headers: authorization });
if (!read.ok) throw new Error(`GET failed: ${read.status} ${await read.text()}`);

const current = await read.json();
const revision = read.headers.get("etag") ?? String(current.revision);

// Preserve the full collection and change only the intended block.
const links = current.data.map((block) =>
  block.id === "portfolio-main"
    ? { ...block, title: "Work and case studies" }
    : block
);

const write = await fetch(endpoint, {
  method: "PUT",
  headers: {
    ...authorization,
    "Content-Type": "application/json",
    "If-Match": revision
  },
  body: JSON.stringify({ links })
});

if (!write.ok) throw new Error(`PUT failed: ${write.status} ${await write.text()}`);
console.log(await write.json());
curl · n8n · OpenAPI

使用本机 n8n 节点或来自 HTTP 客户端、生成的客户端、后端或 CI 运行程序的相同合约。

OrbitPage 不需要 SDK:任何可以发送 JSON、Bearer 身份验证和标准 GET、POST、PUT、PATCH 和 DELETE 请求的 HTTPS 客户端都是兼容的。下面的模式涵盖了集成必须显式处理的有状态部分。

01

原生 n8n 节点

安装 n8n-nodes-orbitpage,并使用个人令牌和 Base URL 创建 OrbitPage API 凭据。连接测试会安全读取工作区;随后,引导式操作会处理路径、权限、项目关联和带修订控制的写入,且不会把密钥保存到工作流 JSON 中。

02

草案和发布

配置文件、主题、页面和支持的设置默认写入需要 If-Match 并更新草稿。添加 ?publish=1 以获得符合条件的立即发布,或查看几个延迟的更改并调用 POST /publication 一次。链接 PATCH 和 PUT 立即发布。

03

直接媒体上传

先预留上传,将数据发送到返回的存储 URL,然后完成操作。OrbitPage bearer token 只能发送到 orbitpage.com;存储请求只能使用返回的方法和临时标头。

04

审查了 AI 提交

计划返回经过验证的预览,而不改变页面。存储并查看其previewToken,然后准确提交该提案。仅当自动化被授权公开结果时,才在提交正文中设置发布。

原生n8n快速入门n8n
Install community node: n8n-nodes-orbitpage

Credential: OrbitPage API
OrbitPage API Token: op_pat_...
OrbitPage Base URL: https://orbitpage.com
Connection test: GET /api/v1/workspace

First safe workflow step:
Node: OrbitPage
Resource: Workspace & Draft
Operation: Get Workspace Overview

First revision-controlled write:
Resource: Theme
Operation: Replace Entire Theme Draft
Revision Check: Use Latest Automatically (Recommended)
三步媒体上传HTTP + JSON
# 1. Reserve an upload and receive uploadUrl, slot and uploadToken
POST /api/v1/media/uploads/reserve
{ "filename": "cover.jpg", "contentType": "image/jpeg", "sizeBytes": 245760 }

# 2. Upload the bytes directly using the returned URL, method and headers
# Do not forward the OrbitPage Authorization header to the storage URL.

# 3. Register the uploaded object in the workspace
POST /api/v1/media/uploads/finalize
{ "slot": "<slot>", "uploadToken": "<uploadToken>" }
审查优先的人工智能流程HTTP + JSON
# 1. Generate a validated preview without changing the page
POST /api/v1/ai/plan
{ "message": "Make the primary CTA clearer" }

# 2. Review the returned operations and previewToken

# 3. Apply the exact reviewed preview; publishing remains explicit
POST /api/v1/ai/commit
{ "previewToken": "<previewToken>", "publish": false }
凭证测试

将 https://orbitpage.com 用作 Base URL,不要附加 /api/v1。成功保存时会读取 /api/v1/workspace,并在不更改数据的情况下验证令牌、工作区绑定和 workspace:read 权限。

n8n 故障排除

401 错误需要有效的替换令牌,403 错误表示缺少权限。若反复发生重定向,请检查 Base URL 或反向代理。向支持团队提供状态和 JSON 代码,但绝不要提供密钥。

阅读完整的本机 n8n 节点指南

操作

将自动化凭证视为短暂的、可观察的生命周期。

工作区支持每个用户最多 10 个活动个人令牌。帐户列表显示每个令牌的前缀、范围、创建和到期日期以及最近的使用情况。最后使用的时间戳最多每五分钟写入一次。

GitHub ActionsYAML
name: Update OrbitPage
on: workflow_dispatch

jobs:
  update:
    runs-on: ubuntu-latest
    env:
      ORBITPAGE_TOKEN: ${{ secrets.ORBITPAGE_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: node scripts/update-orbitpage.mjs
  • 按系统和环境命名令牌 - 例如,“GitHub Actions · production”。
  • 通过创建替换、更新秘密存储、测试一次读取、然后撤销旧令牌来轮换。
  • 在涉嫌披露、所有权变更或工作流程停用后立即撤销。撤销在下一次请求时生效。
  • 不要构建长期共享令牌。单独的凭据使日志、轮换和事件响应易于理解。
失败处理

HTTP 状态和机器可读代码的分支。

错误使用带有错误和代码的 JSON。不要解析人类句子来控制工作流程。大多数 4xx 响应需要更改请求或凭据;只有修订冲突和速率限制属于自动重试路径。

400INVALID_JSON · LINKS_REQUIRED · LINK_PATCH_INVALID修复页面架构拒绝的请求正文或字段。
401PERSONAL_TOKEN_*替换丢失、无效、过期或撤销的令牌。不要使用相同的密码重试。
403PERSONAL_TOKEN_SCOPE_DENIED · SYSTEM_LINK_PROTECTED使用所需范围或停止:当前身份不允许执行此操作。
404LINK_NOT_FOUND刷新收藏;块 ID 可能已被删除或替换。
409revision_conflict再次执行 GET,将预期更改重新应用到新状态,并使用新修订号重试。
413REQUEST_TOO_LARGE将 JSON 正文保持在 768 KiB 或以下。
415UNSUPPORTED_CONTENT_ENCODING发送未压缩的 JSON 请求正文。
428revision_required使用最新 GET 返回的修订版或 ETag 添加 If-Match。
429RATE_LIMITED等待 Retry-After 指定的时间,然后使用指数退避和随机抖动重试。

当前限制为每个令牌每分钟 120 个请求、每天 5,000 个请求。滥用防护可能收紧限制;请始终遵循 Retry-After。

安全

安全集成是狭窄的、秘密的和修订感知的。

01

最低权限

使用只读,除非作业必须发布。令牌功能永远不能超出所有者当前的工作区角色。

02

仅服务器端

从受信任的脚本、后端或 CI 运行程序调用 API。浏览器捆绑包、移动客户端或公共存储库无法保守承载秘密。

03

禁止盲写

请在写入前立即执行 GET 请求并使用 If-Match。如果 409 错误返回 revision_conflict,请重新读取资源并再次应用预期更改;对于其他错误代码,请解决文档所述的业务条件。

04

验证结果

检查响应状态、修订和返回的数据。对于重要更改,请在发布后打开公共页面并在失败时发出警报,而无需记录令牌。

版界

个人令牌自动化 REST API 是一种托管 SaaS 功能。

开源仓库包含内置仪表板使用的 Express API,但该内部管理员会话 API 不是同一个版本化自动化契约。不要把 op_pat 令牌发送到自托管服务器,也不要把自托管管理员 JWT 发送到 orbitpage.com/api/v1。

托管工作区

使用本指南、OpenAPI 合约和在帐户中创建的个人代币。

自托管实例

使用同一受信任源上的捆绑仪表板。存储库文档解释了贡献者和维护者的内部边界。

解读开源API边界
Automation REST API and personal tokens | OrbitPage