Create Page

POST /api/v1/content/projects/:projectId/pages

Creates a page in a project. Two kinds of page are creatable:

CUSTOM — a bespoke merchant page with a caller-supplied handle/path. Starts blank unless you pass basedOn.
Resource-backed templates (PRODUCT, COLLECTION, PAGE, BLOG, ARTICLE) — a per-resource override / custom template. Clones the project’s shared default template for that type when one exists; otherwise starts blank. Pass basedOn to clone a specific page instead.

This endpoint creates one new page per call (a per-resource copy). To assign many Shopify resources to a single shared template page without copying content, use Assign template resources instead.

Requires a Content API key. See Authentication.

Path parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID

Request body

Field	Type	Required	Description
`type`	string	Yes	`CUSTOM`, `PRODUCT`, `COLLECTION`, `PAGE`, `BLOG`, or `ARTICLE`
`handle`	string	Yes	For `CUSTOM`, a page handle/path (e.g. `pages/gift-shop`). For resource-backed types, the Shopify resource handle (e.g. `summer-sale`), kept verbatim.
`name`	string	No	Display name. Defaults to the normalized handle.
`locale`	string	No	Assignment locale. Defaults to the global/default assignment (`""`).
`basedOn`	string	No	Source page ID to clone layout items from. The source page must be assigned to the same project. When omitted for a resource-backed type, the shared default template for that type is cloned when one exists; otherwise the page starts blank.
`shopifyResourceId`	string	No	Optional non-empty Shopify resource id (gid). Validated when present; persisted for resource-backed types (`PRODUCT`/`COLLECTION`/`PAGE`/`BLOG`/`ARTICLE`); not stored for `CUSTOM`.

POST /projects/:projectId/pages also preserves the legacy POST-as-delete fallback. A body containing pageIds or handles is treated as a bulk-delete request. Use the create fields above for page creation.

Example

cURL
TypeScript

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://studio.weaverse.io/api/v1/content/projects/clx1abc23def456ghij/pages" \
  -d '{
    "type": "CUSTOM",
    "name": "Gift Shop",
    "handle": "pages/gift-shop"
  }'

const res = await fetch(
  `https://studio.weaverse.io/api/v1/content/projects/${projectId}/pages`,
  {
    method: 'POST',
    headers: {
      Authorization: ['Bearer', API_KEY].join(' '),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'CUSTOM',
      name: 'Gift Shop',
      handle: 'pages/gift-shop',
    }),
  },
)

const created = await res.json()

Clone an existing layout

Pass basedOn with a page ID from List Pages to clone the source page’s layout items into the new page.

{
  "type": "CUSTOM",
  "name": "Wholesale Landing Page",
  "handle": "pages/wholesale",
  "basedOn": "clz5wxy12abc345gift"
}

The source page must be assigned to the same project. Cross-project source IDs return 404 PAGE_NOT_FOUND.

Create a resource-backed override

Create a per-resource override (custom template) so a specific resource page — for example a collection PLP — can carry editorial/content blocks. When you omit basedOn, the project’s shared default template for that type is cloned when one exists; otherwise the page starts with a blank root. Pass shopifyResourceId to bind the Shopify resource for Studio’s assignment UX.

{
  "type": "COLLECTION",
  "name": "Summer Sale PLP",
  "handle": "summer-sale",
  "shopifyResourceId": "gid://shopify/Collection/123456789"
}

This creates one page copy for the resource. If a live assignment already exists for the same type, handle, and locale/market, the request returns 409 CONFLICT and creates nothing — read the existing page with Get Page or edit its items with Update Page instead. To point several resources at one shared template page rather than creating a copy per resource, see Assign template resources.

Response

{
  "object": "page_create",
  "page": {
    "object": "page",
    "id": "clz5wxy12abc345gift",
    "type": "CUSTOM",
    "handle": "pages/gift-shop",
    "locale": "",
    "items": [
      {
        "id": "019503a2-c4b6-7c9d-8e3f-1a2b3c4d5e6f",
        "type": "root",
        "data": {},
        "children": null
      }
    ],
    "updatedAt": "2026-07-09T10:30:00.000Z",
    "meta": {
      "inherited": false,
      "sourceProjectId": "clx1abc23def456ghij",
      "depth": 0
    }
  }
}

The nested page object follows the same shape as Get Page.

Errors

Code	Status	When
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	API key does not have access to this project
`PROJECT_NOT_FOUND`	404	Project does not exist or was deleted
`PAGE_NOT_FOUND`	404	`basedOn` does not resolve to a live page in this project
`CONFLICT`	409	A live page already exists for the same type, handle, and locale/market assignment
`INVALID_PARAMS`	400	Invalid body, unsupported type (creatable types are `CUSTOM`, `PRODUCT`, `COLLECTION`, `PAGE`, `BLOG`, `ARTICLE`), or missing/empty handle
`INTERNAL_ERROR`	500	Unexpected server error

Overview

Hooks

Components

Utilities & Types

Content API

Create Page

Create Page

Path parameters

Request body

Example

Clone an existing layout

Create a resource-backed override

Response

Errors

​Create Page

​Path parameters

​Request body

​Example

​Clone an existing layout

​Create a resource-backed override

​Response

​Errors

Create Page

Path parameters

Request body

Example

Clone an existing layout

Create a resource-backed override

Response

Errors