# Landing Pages

> REST reference for graph8 landing pages — clone from URL or homepage, edit, publish to Cloudflare Pages

Source: https://docs.graph8.com/developers/landing-pages/

The Landing Pages API exposes graph8's clone-first page builder: clone any URL into a fully editable replica, modify text + images + design tokens via chat or direct edits, then publish to a Cloudflare Pages subdomain.

> **Caution:**
> `POST /publish` deploys to a public URL. Make sure your changes are ready before publishing.

> **Note: Auth**
> Every call needs `Authorization: Bearer $G8_API_KEY`. The `X-Org-Id` is bound to the key automatically. [Get a key in 30 seconds →](https://docs.graph8.com/developers/authentication/)

## 30-second start

List your landing pages:

**cURL**

```bash
curl 'https://be.graph8.com/api/v1/pages?status=published' \
  -H "Authorization: Bearer $G8_API_KEY"
```

**TypeScript**

```typescript
import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const pages = await g8.pages.list({ status: 'published' });
console.log(pages);
```

**CLI**

```bash
# Use the REST API directly — no dedicated CLI command yet
curl 'https://be.graph8.com/api/v1/pages' \
  -H "Authorization: Bearer $(g8 whoami | grep -oE '[a-f0-9]{40}' | head -1)"
```

**MCP**

Ask your agent: *"List my landing pages"* → tool exists in MCP `all` mode; uses the same backend.

## Quick reference

| Endpoint | Method | Purpose |
|---|---|---|
| `/pages` | GET | List landing pages |
| `/pages/{id}` | GET | Get a page (HTML, design tokens, image refs, version) |
| `/pages` | POST | Create from template / clone homepage / clone URL |
| `/pages/{id}` | PATCH | Update page (HTML diff, brand overrides) |
| `/pages/{id}` | DELETE | Delete |
| `/pages/{id}/publish` | POST | Deploy to Cloudflare Pages |
| `/pages/{id}/versions` | GET | List version history |
| `/pages/{id}/versions/{version_id}` | GET | Restore / preview a previous version |
| `/pages/{id}/chat` | POST | Send a chat message that edits the page |

## Three ways to create

### 1. From a template

```bash
POST /api/v1/pages
Content-Type: application/json

{
  "template": "demo" | "lead_magnet" | "product_launch" | "event" | "free_trial",
  "title": "Q3 PLG Demo Page",
  "campaign_id": "cmp_abc123"
}
```

Templates ship with sensible defaults — hero, value props, social proof, CTA. Customize via PATCH or the chat surface afterwards.

### 2. Clone your homepage

```bash
POST /api/v1/pages
{ "clone_source": "homepage", "title": "Cloned home" }
```

Pulls the org's primary website via Firecrawl, extracts design tokens (colors, fonts, components), sanitizes the HTML, injects deterministic `data-g8-id` element IDs, and creates a fully editable replica. The clone preserves the visual identity so further pages live in the same brand system.

### 3. Clone from any URL

```bash
POST /api/v1/pages
{ "clone_source": "url", "url": "https://competitor.com/pricing", "title": "Competitor pricing analog" }
```

Same pipeline as homepage clone, but from an arbitrary URL. Useful for matching a competitor's flow or replicating a hero page you like.

## Edit via chat

```bash
POST /api/v1/pages/{page_id}/chat
{
  "message": "Change the hero headline to 'Stop paying for stale data' and make the primary CTA pink."
}
```

Returns the diff applied to the page plus a new version. The chat surface is conversational — it can target specific elements ("the second testimonial"), apply brand-token changes, and add or remove sections.

## Edit via PATCH

```bash
PATCH /api/v1/pages/{page_id}
{
  "html": "<...full HTML...>",
  "design_tokens": {
    "colors": { "primary": "#9C73FF", "secondary": "#00CAEB" },
    "fonts": { "heading": "Aeonik", "body": "Inter" }
  }
}
```

Use this for programmatic edits — e.g. propagating a brand-token change across multiple pages.

## Versions

```bash
GET /api/v1/pages/{id}/versions
# { data: [{ version_id, created_at, label, chat_message? }, ...] }

GET /api/v1/pages/{id}/versions/{version_id}
# Returns the full HTML snapshot of that version (for preview / restore)
```

Every chat edit creates a version. Restore by PATCHing the current page with a version's HTML.

## Publish

```bash
POST /api/v1/pages/{page_id}/publish
```

Deploys the current version to Cloudflare Pages at `https://g8-lp-{org_sha256[:8]}.pages.dev/{slug}`. Returns the public URL.

The CF Pages backend uses **Direct Upload** — no DNS / domain config needed. For a custom domain, attach via Cloudflare dashboard manually (custom-domain mapping API is not yet exposed).

## List + delete

```bash
GET /api/v1/pages?campaign_id=cmp_abc123&status=published
DELETE /api/v1/pages/{page_id}
```

## Credit costs

| Operation | Credits |
|---|---|
| List / get / versions | Free |
| Create (template) | Free |
| Create (clone) | Free — but Firecrawl + AI extraction may take 30-90 seconds |
| Edit via PATCH | Free |
| Edit via chat | **1 per 1,000 AI tokens** (the chat is LLM-powered) |
| Publish | Free (Cloudflare Pages is bundled) |

## Errors

| Status | Cause | Fix |
|---|---|---|
| `401` | Missing or invalid `Authorization: Bearer` header | [Get a key](https://docs.graph8.com/developers/authentication/) |
| `402` | Out of credits (waterfall enrichment, AI generation, voice minutes) | Top up in **Settings → Billing**, or switch to Platform |
| `404` | Resource ID doesn't exist | List first to verify the ID |
| `422` | Validation error in request body | Inspect `error.message` + `error.field` in the response |
| `429` | Rate limit (50 rps per org) | Backoff per `Retry-After` header. See [Rate Limits](https://docs.graph8.com/developers/rate-limits/) |
| `5xx` | graph8 error | Retry with exponential backoff (5s → 30s → 120s) |

The full error envelope shape: `{ "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }`. Include the `request_id` in any support ticket. See [Errors](https://docs.graph8.com/developers/errors/) for the canonical reference.

## See also

- [SDK pages methods](https://docs.graph8.com/developers/sdk/#landing-pages)
- [Pricing](https://docs.graph8.com/developers/pricing/) — credit matrix