> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SwiftPage API overview

> Authentication, public endpoints, page and Shopify proxy routes, billing, and the App Proxy tracking endpoint.

# SwiftPage API overview

This page documents SwiftPage's externally reachable app and storefront endpoints. Operational maintenance interfaces are outside this public reference.

## Authentication

Authenticated endpoints require a Shopify App Bridge session token (JWT) in the `Authorization` header:

```text theme={null}
Authorization: Bearer <session-token>
```

SwiftPage validates that the token was issued for the app and that its destination identifies a Shopify shop. That verified destination scopes the authenticated request to the current shop.

## Read-only request

The health route needs no authentication, so it is the simplest request to try. Set `APP_ORIGIN` to your deployed app's HTTPS origin, without a trailing slash.

```bash theme={null}
curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/health"
```

## Public endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/health` | Health check: `{ status, app, timestamp }` |
| `GET` | `/auth/install?shop={shop}` | Start OAuth; redirects to Shopify authorization |
| `GET` | `/auth/callback?shop={shop}&code={code}&hmac={hmac}&state={state}` | OAuth callback; verifies HMAC and state, completes authorization, and registers supported webhooks |
| `POST` | `/webhooks/shopify` | Webhook receiver (HMAC-verified) |

## Shop and templates

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/me` | Current shop info: `shop`, `plan`, `entitlements`, `canPublish`, `installedAt`, and `setup` timestamps |
| `GET` | `/api/templates` | List starter templates (id, name, category, description, layout) |
| `POST` | `/api/support` | Store an authenticated support request: `email`, `message` (10–5000 chars) |
| `POST` | `/api/setup/skip` | Record the initial dismissal of the setup modal |
| `POST` | `/api/setup/confirm-theme` | Record merchant confirmation of the theme block when status is unavailable |

## Pages

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/pages` | List pages for the shop |
| `GET` | `/api/pages/:id` | Get one page, including its layout |
| `POST` | `/api/pages` | Create a page: `title`, `handle`, optional `seo_title`, `seo_description`, `layout_json`, `template_id` |
| `PUT` | `/api/pages/:id` | Update a page (all fields optional) |
| `DELETE` | `/api/pages/:id` | Delete a page; if it is published on Shopify, the Shopify page is deleted first |
| `POST` | `/api/pages/:id/publish` | Create or update the Shopify Page, synchronize its published content, and save a version |
| `POST` | `/api/pages/:id/unpublish` | Set the Shopify Page to unpublished |
| `POST` | `/api/pages/:id/export` | Export the page as a ZIP (Scale or Agency) |

Sending `X-SwiftPage-One-Click: 1` on publish uses the Growth one-click publish shortcut; without the entitlement it is rejected with `403 plan_limit`. Publishing returns `403` when the plan page limit is reached or when the metaobject scopes are missing (reauthorize prompt).

CSS dimension fields (`width`, `height`, `padding`, `margin`, `maxWidth`) in section settings and mobile overrides are sanitized on update.

## Shopify proxy

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/shopify/products?query={query}` | Search products |
| `GET` | `/api/shopify/collections?query={query}` | Search collections |
| `POST` | `/api/shopify/files/image-upload` | Create a staged image upload: `filename`, `mimeType`, `fileSize` |
| `POST` | `/api/shopify/files/complete` | Register a staged upload as a Shopify file: `resourceUrl`, optional `alt` |

When the Growth image-compression setting is enabled, the editor resizes eligible JPEG/PNG/WebP selections before requesting the staged target. GIF and SVG uploads are preserved unchanged.

## Billing

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/billing` | Current plan, published page count, subscription GID, interval, trial eligibility, and plan list |
| `POST` | `/api/billing/subscribe` | Create an app-managed charge: `planId` (`growth`, `pro`, `scale`, `free`), optional `interval` (`monthly`/`annual`), and a client-stable `idempotencyKey`. Returns Shopify's `confirmationUrl` |
| `POST` | `/api/billing/cancel` | Cancel the active subscription |

Paid requests require a 16–128 character `idempotencyKey`; the client reuses the same key when offering a retry. Selecting `free` cancels the active subscription. Paid entitlements are not granted until Shopify reports an active subscription. Requires the `admin` collaborator role.

## Feature endpoints

Premium capabilities live under `/api/features/*`. Each route enforces a server-side entitlement for the authenticated shop; calls below the required tier return `403 plan_limit`.

| Method | Path | Entitlement (min tier) |
| - | - | - |
| `POST` | `/api/features/ai/copy` | `aiCopyStarter` (Free) |
| `POST` | `/api/features/ai/layout` | `aiLayoutGeneration` (Growth) |
| `POST` / `GET` | `/api/features/reusable-blocks` | `reusableBlocks` (Growth) |
| `PUT` / `DELETE` | `/api/features/reusable-blocks/:id` | `reusableBlocks` (Growth) |
| `POST` | `/api/features/theme-sync` | `themeSectionSync` (Growth) |
| `POST` | `/api/features/seo-audit/:pageId` | `seoAudits` (Pro) |
| `POST` | `/api/features/experiments` | `abTesting` (Pro) |
| `POST` | `/api/features/experiments/:id/complete` | `abTesting` (Pro) |
| `POST` | `/api/features/localizations/:pageId` | `localization` (Pro) |
| `POST` | `/api/features/content-sync` | `contentSyncing` (Pro) |
| `POST` | `/api/features/funnels` | `funnelsPostPurchase` (Scale) |
| `POST` | `/api/features/3d-models/:pageId` | `model3dSupport` (Scale) |
| `POST` | `/api/features/collaborators` | `collaborationRoles` (Scale) |
| `POST` | `/api/features/webhooks` | `apiWebhooks` (Scale) |
| `GET` / `PUT` | `/api/features/shop-settings` | `customFontsCss` (Growth) |
| `GET` / `POST` | `/api/features/experiments/:id/schedule` | `advancedExperiments` (Scale) |
| `GET` / `POST` | `/api/features/org` | `multiStore` (Agency) |
| `GET` | `/api/features/migration/export` | `migration` (Agency) |
| `POST` | `/api/features/migration/import` | `migration` (Agency) |

## App Proxy

| Method | Path | Description |
| - | - | - |
| `POST` | `/apps/swiftpage/track` | Signed App Proxy endpoint that records anonymous `visitor_id`, `page_view`, and `conversion` events for the rolling 90-day analytics surface |

## Maintenance

Operational repair interfaces are not part of SwiftPage's public API contract and are intentionally omitted from this reference.

## Rate limiting

Authenticated `/api/pages` routes use a per-shop fixed-window limit of 60 requests per 60 seconds, keyed by shop domain. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Exceeded windows return `429 rate_limited` with a `Retry-After` header.

## Errors

All errors use:

```json theme={null}
{ "error": "error_code", "message": "Human-readable message", "details": [] }
```

Common codes include `bad_request`, `validation_error`, `unauthorized`, `forbidden`, `rate_limited`, `plan_limit`, `not_found`, `publish_error`, `billing_error`, `billing_request_in_progress`, `billing_request_expired`, `idempotency_conflict`, `billing_sync_error`, `duplicate_handle`, `delete_error`, and `server_error`.

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [SwiftPage](https://docs.pcnaid.com/nodes/shopify/swiftpage/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/swiftpage/developer/index)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.