Automation REST API

Choose the right API

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

Complete endpoint reference

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 and use a token

Open Dashboard > Team > 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

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

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

Replace the collection

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

n8n and end-to-end workflows

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.

OrbitPage is approved by n8n as a Verified Community Node; it remains community-maintained and is not preinstalled. Once it appears in the verified catalog, an instance owner or admin can search for OrbitPage in the + nodes panel, select More from the community and choose Install, including on n8n Cloud. If it is not listed yet, Cloud users must wait for catalog publication; self-hosted users can install n8n-nodes-orbitpage through Settings → Community Nodes.

Installation, downloads and example workflows

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 n8n community node guide

CI, rotation and revocation

A workspace supports up to ten active personal tokens per user. The Team token 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.

Errors and retries

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.

Validate outcomes

Check response status, revision and returned data. For important changes, open the public page after publication and alert on failure without logging the token.

SaaS and open source

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.