Automate OrbitPage without sharing a dashboard session.

Three credential boundaries cover three different jobs.

This page documents the versioned REST boundary. An OrbitPage token is not an OpenAI provider key and never authenticates private dashboard endpoints.

Every supported dashboard operation, grouped by the surface it controls.

Paths below are relative to https://orbitpage.com/api/v1. Method, path and scope are the stable integration contract; request schemas, formats, enum values and response models live in the linked OpenAPI 3.1 document. Unknown routes return 404 and unsupported methods are never silently converted.

Create one token for one automation and one environment.

Open Dashboard > Account > Personal API tokens. Give the token a name that identifies its owner and purpose, choose full workspace, read-only workspace, links-only or individual resource scopes, then select an expiry of 30, 90 or 365 days—or no expiry when a documented rotation process already exists.

export ORBITPAGE_TOKEN='op_pat_...'

curl --silent --show-error --include \
  --header "Authorization: Bearer $ORBITPAGE_TOKEN" \
  https://orbitpage.com/api/v1/links

$env:ORBITPAGE_TOKEN = 'op_pat_...'
$headers = @{ Authorization = "Bearer $env:ORBITPAGE_TOKEN" }

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

Read the collection and capture its revision before every change.

The response body contains the ordered blocks in data and the current numeric revision. The same revision appears in X-OrbitPage-Revision and as a weak ETag. Save either value for If-Match; do not guess or cache it across unrelated runs.

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"
  }
}

Use PATCH for the smallest change to an existing block.

URL-encode the ID returned by GET and send only the fields that should change. OrbitPage merges the patch into the existing block, protects identity and analytics fields, validates the complete page against its schema and plan, then publishes immediately.

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
  }'

Use PUT only when the collection itself must change.

PUT replaces the complete ordered collection. It is the operation for adding a block, removing a block or changing page order. It is not a shortcut for updating one title: omitting a block removes it from the page.

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());

Use the native n8n node or the same contract from an HTTP client, generated client, backend or CI runner.

OrbitPage does not require an SDK: any HTTPS client that can send JSON, Bearer authentication and standard GET, POST, PUT, PATCH and DELETE requests is compatible. The patterns below cover the stateful parts that an integration must handle explicitly.

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)

# 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>" }

# 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 }

Read the complete native n8n node guide

Treat automation credentials as short, observable lifecycles.

A workspace supports up to ten active personal tokens per user. The Account list shows each token's prefix, scopes, creation and expiry dates, and recent use. Last-used timestamps are intentionally written at most once every five minutes.

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

• Name tokens by system and environment—for example, “GitHub Actions · production”.
• Rotate by creating the replacement, updating the secret store, testing one read, then revoking the old token.
• Revoke immediately after suspected disclosure, ownership change or workflow retirement. Revocation takes effect on the next request.
• Do not build a long-lived shared token. Separate credentials make logs, rotation and incident response understandable.

Branch on the HTTP status and machine-readable code.

Errors use JSON with error and code. Do not parse the human sentence to control a workflow. Most 4xx responses require changing the request or credential; only revision conflicts and rate limits belong in an automatic retry path.

Current guardrails allow 120 requests per minute and 5,000 requests per day per token. Limits may become stricter during abuse protection; always honor Retry-After.

A safe integration is narrow, secret and revision-aware.

The personal-token Automation REST API is a managed SaaS capability.

The open-source repository contains an Express API used by its bundled dashboard, but that internal admin-session API is not the same versioned automation contract. Do not send an op_pat token to a self-hosted server and do not send a self-hosted admin JWT to orbitpage.com/api/v1.