External endpoints

Each section below documents one resource group under /api/v1.1/*. Authentication applies to every endpoint — see API overview for the Authorization header format.

For AI agent integrations, most of these operations are also exposed as MCP tools — see MCP server, which also lists the seven tools that have no REST equivalent and the endpoints that share a path with a tool but not its shape.

Permission levels used in this page:

• Read — requires a valid API key (any key).
• Write — requires a key with writeAccess enabled.

---

Ads

Ad platform configurations (Facebook, TikTok, Bing Ads) linked to your deployment.

Method	Path	Description	Access
GET	/api/v1.1/ads	List all ad platforms.	Read
GET	/api/v1.1/ads/:id	Get a single ad platform by ID.	Read

# List all ad platforms
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/ads

# Get one platform
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/ads/clxyz123

---

Funnels

Read-only access to your live funnels and the pages they reference. These endpoints read the live Funnel table directly, so they always reflect the current state of your funnels.

Method	Path	Description	Access
GET	/api/v1.1/funnels	List all funnels (funnelId, name, stepCount, updatedAt).	Read
GET	/api/v1.1/funnels/:funnelId	Get a funnel with its full step list (steps[] of { pageId, stepSlug, type }).	Read
GET	/api/v1.1/funnels/:funnelId/pages	List the published pages referenced by the funnel ({ pageId, slug, name, type, stepSlug }).	Read

# List funnels
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/funnels

# Get one funnel with its steps
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/funnels/clxyz789

Example GET /api/v1.1/funnels/:funnelId response:

{
  "funnel": {
    "funnelId": "clxyz789",
    "name": "Summer Sale",
    "steps": [
      { "pageId": "p_lp1", "stepSlug": "landing", "type": "custom" },
      { "pageId": "p_co", "stepSlug": "checkout", "type": "checkout" }
    ],
    "updatedAt": "2026-06-18T12:00:00.000Z"
  }
}

GET /api/v1.1/funnels/:funnelId/pages returns only the funnel’s referenced pages that are currently PUBLISHED.

---

Media

Upload, download from URL, or AI-generate media assets.

Method	Path	Description	Access
GET	/api/v1.1/media	List uploaded media assets.	Read
POST	/api/v1.1/media/upload	Upload a file (multipart) or download from a URL.	Write
POST	/api/v1.1/media/generate	AI-generate an image. Requires an LLM configured in Settings.	Write

POST /api/v1.1/media/upload accepts images (jpeg, jpg, png, webp, gif) and video (mp4, webm). SVG uploads are rejected for security reasons.

# Upload a file
curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/image.jpg" \
  https://your-shop.com/api/v1.1/media/upload

# Download from URL
curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}' \
  https://your-shop.com/api/v1.1/media/upload

---

Orders

Order listing, retrieval, delivery confirmation, and refunds. Customer data is privacy-protected — email addresses are masked, and addresses expose country only.

Method	Path	Description	Access
GET	/api/v1.1/orders	List orders. Supports filters: status, dateFrom, dateTo.	Read
GET	/api/v1.1/orders/:orderId	Get a single order by ID.	Read
POST	/api/v1.1/orders/:orderId/deliver	Mark a SHIPPED order as DELIVERED. Only valid for orders currently in SHIPPED status.	Write
POST	/api/v1.1/orders/:orderId/refund	Refund an order. Request body specifies refund type (full, fixed amount, percentage) and amount.	Write

# List recent paid orders
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://your-shop.com/api/v1.1/orders?status=PAID&dateFrom=2026-01-01"

# Mark an order as delivered
curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/orders/12345/deliver

---

Pages

Read-only access to your live published pages. These endpoints read the live Page table directly and only return pages whose status is PUBLISHED. Both Puck (component JSON, in document) and HTML editor (in html) page types are exposed.

Method	Path	Description	Access
GET	/api/v1.1/pages	List published pages (pageId, slug, name, type, updatedAt).	Read
GET	/api/v1.1/pages/:pageId	Get a single published page with full content. Returns 404 if the page is not published.	Read

# List published pages
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/pages

# Get one published page
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/pages/clxyz456

Example GET /api/v1.1/pages/:pageId response:

{
  "page": {
    "pageId": "clxyz456",
    "slug": "my-checkout",
    "name": "Checkout",
    "type": "checkout",
    "editorType": "PUCK",
    "document": { "content": [], "root": {} },
    "html": null,
    "meta": {},
    "updatedAt": "2026-06-18T12:00:00.000Z"
  }
}

---

Products

Products are read from the connected ecommerce adapter (Shopify, WooCommerce, or Picocart). There are no write endpoints — manage products in your ecommerce platform.

Method	Path	Description	Access
GET	/api/v1.1/products	List products. Supports search and get-by-ID.	Read
GET	/api/v1.1/products/:id	Get a single product with variants.	Read

# List products
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/products

# Search products
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://your-shop.com/api/v1.1/products?search=shirt"

---

Stats

Funnel conversion statistics and product-level stats. All metrics are counted by unique user.

Method	Path	Description	Access
GET	/api/v1.1/stats/funnels/:funnelId	Conversion stats for a specific funnel (views, checkouts, purchases, upsell acceptance).	Read
GET	/api/v1.1/stats/products/:productId	Stats for a specific product.	Read

# Get funnel stats
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/stats/funnels/clxyz789

---

Templates

Page templates available for use when creating pages via the API.

Method	Path	Description	Access
GET	/api/v1.1/templates	List all available page templates with their keys and metadata.	Read
GET	/api/v1.1/templates/:key	Get a template’s full Puck JSON structure.	Read

# List templates
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/templates

# Get template detail
curl -H "Authorization: Bearer YOUR_KEY" \
  https://your-shop.com/api/v1.1/templates/CHECKOUT

---

Changed

• The pages and funnels endpoints now read the live Page / Funnel tables instead of a frozen publication snapshot, so they always reflect current data. As part of this change the publication-versioning fields (version, contentHash, revisionId) were removed from the responses, the page-detail content field is now document (the live publishedData), and the previously documented write endpoints for pages and funnels (POST/PUT/DELETE, including PUT /api/v1.1/pages/:pageId) are not part of this surface — these resources are read-only.

Caveats

• Response field stability is not guaranteed before v1. Pin against a specific autonnel release in production integrations.
• All responses are JSON. There is no XML or form-encoded response mode.
• Failed requests return JSON { "error": { "message": "...", "type": "..." } } with an appropriate HTTP status code.
• The POST /orders/:id/deliver endpoint only transitions orders that are currently in SHIPPED status. Attempting it on any other status returns 400 Bad Request.

Related

• API keys — generate and manage API keys.
• MCP server — the agent-facing surface, and where it diverges from these endpoints.
• API overview — authorization model and write access.