API REST di automazione

Scegli l'API corretta

Questa pagina documenta il confine REST versionato. Un token OrbitPage non è una chiave provider OpenAI e non autentica mai gli endpoint privati della dashboard.

Reference completa degli endpoint

I percorsi seguenti sono relativi a https://orbitpage.com/api/v1. Metodo, percorso e scope costituiscono il contratto stabile di integrazione; schemi delle richieste, formati, valori enum e modelli di risposta sono nella specifica OpenAPI 3.1 collegata. Le route sconosciute restituiscono 404 e i metodi non supportati non vengono mai convertiti in modo implicito.

Crea e usa un token

Apri Dashboard > Team > Token API personali. Assegna un nome che identifichi proprietario e scopo, scegli accesso completo al workspace, workspace in sola lettura, solo link oppure singoli scope di risorsa, quindi imposta una scadenza di 30, 90 o 365 giorni—oppure nessuna scadenza se esiste già un processo di rotazione documentato.

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

Leggi la collezione

Il body della risposta contiene i blocchi ordinati in data e la revisione numerica corrente. La stessa revisione compare in X-OrbitPage-Revision e come ETag debole. Conserva uno dei due valori per If-Match; non indovinarlo e non riutilizzarlo tra esecuzioni non correlate.

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

Modifica un blocco

Codifica nell'URL l'ID restituito da GET e invia solo i campi da cambiare. OrbitPage unisce la patch al blocco esistente, protegge identità e campi analytics, valida l'intera pagina rispetto a schema e piano, quindi pubblica immediatamente.

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

Sostituisci la collezione

PUT sostituisce l'intera collezione ordinata. È l'operazione da usare per aggiungere un blocco, rimuoverlo o cambiare l'ordine della pagina. Non è una scorciatoia per modificare un solo titolo: omettere un blocco lo rimuove dalla pagina.

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 e flussi end-to-end

OrbitPage non richiede un SDK: è compatibile qualsiasi client HTTPS in grado di inviare JSON, autenticazione Bearer e richieste standard GET, POST, PUT, PATCH e DELETE. I modelli seguenti coprono le parti con stato che un'integrazione deve gestire esplicitamente.

OrbitPage è approvato da n8n come Verified Community Node; resta gestito dalla community e non è preinstallato. Quando compare nel catalogo verificato, il proprietario o un amministratore dell'istanza può cercare OrbitPage dal pannello + dei nodi, selezionare More from the community e scegliere Install, anche su n8n Cloud. Se non è ancora elencato, su Cloud occorre attendere la pubblicazione nel catalogo; su n8n self-hosted si può installare n8n-nodes-orbitpage da Settings → Community Nodes.

Installazione, download e workflow di esempio

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 }

Leggi la guida completa del community node n8n

CI, rotazione e revoca

Un workspace supporta fino a dieci token personali attivi per utente. L'elenco dei token in Team mostra prefisso, scope, date di creazione e scadenza e utilizzo recente. Il timestamp dell'ultimo uso viene aggiornato intenzionalmente al massimo una volta ogni cinque minuti.

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

• Nomina i token per sistema e ambiente—per esempio “GitHub Actions · produzione”.
• Ruota creando il sostituto, aggiornando il secret store, provando una lettura e poi revocando il vecchio token.
• Revoca immediatamente dopo una possibile esposizione, un cambio di responsabilità o la dismissione del workflow. La revoca ha effetto dalla richiesta successiva.
• Non creare un unico token condiviso e permanente. Credenziali separate rendono comprensibili log, rotazione e risposta agli incidenti.

Errori e tentativi

Gli errori usano JSON con error e code. Non analizzare la frase destinata alle persone per controllare un workflow. La maggior parte delle risposte 4xx richiede di cambiare richiesta o credenziale; solo i conflitti di revisione e i limiti di frequenza appartengono a un percorso di retry automatico.

I limiti attuali consentono 120 richieste al minuto e 5.000 al giorno per token. Le protezioni antiabuso possono renderli più restrittivi; rispetta sempre Retry-After.

Valida il risultato

Controlla stato della risposta, revisione e dati restituiti. Per modifiche importanti, apri la pagina pubblica dopo la pubblicazione e segnala gli errori senza registrare il token nei log.

SaaS e open source

Il repository open source contiene un'API Express usata dalla dashboard inclusa, ma quell'API interna basata sulla sessione admin non è lo stesso contratto versionato per le automazioni. Non inviare un token op_pat a un server self-hosted e non inviare un JWT admin self-hosted a orbitpage.com/api/v1.