> ## Documentation Index > Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it. > Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`. > Define component schemas with `createSchema()` from `@weaverse/hydrogen` (React Router themes) or `@weaverse/next` (Next.js themes). > These docs cover @weaverse/hydrogen, @weaverse/react and @weaverse/core 5.x, and @weaverse/next 1.x. Do not use APIs from other major versions. > For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://docs.weaverse.io/developer-tools/weaverse-mcp # Create a page > Creates one new page in the project. Two kinds of page are creatable: - `CUSTOM`: a bespoke merchant page addressed by a caller-chosen handle/path such as `pages/gift-shop`. Leading slashes are stripped, repeated slashes collapsed and trailing slashes removed. Starts with a blank root item unless `basedOn` is supplied. - Resource-backed types (`PRODUCT`, `COLLECTION`, `PAGE`, `BLOG`, `ARTICLE`): a per-resource override (custom template) for one Shopify resource, where `handle` is the resource handle, kept verbatim. It clones the project's shared default template for that type when one exists, otherwise it starts with a blank root item. Pass `shopifyResourceId` to bind the Shopify resource for Studio's assignment UI. Pass `basedOn` with a page id from the pages list to clone that page's layout instead. The source page must be assigned to the same project; a cross-project or unknown id returns `404 PAGE_NOT_FOUND`. This creates one page copy per call. To point many resources at a single shared template page without copying content, use `POST /projects/{projectId}/template-assignments/{pageId}`. If a live assignment already exists for the same type, handle and locale (or market), the request returns `409 CONFLICT` and creates nothing; read or edit the existing page instead. Any other type, or a missing or empty `handle`, returns `400 INVALID_PARAMS`. Legacy behaviour: a body containing `pageIds` or `handles` is treated as the bulk-delete fallback and returns a `page_delete` result. Prefer `DELETE /projects/{projectId}/pages` for deletion. Required scope: `content:write` (the bulk-delete fallback also requires `content:delete`) ## OpenAPI ````yaml https://studio.weaverse.io/api/v1/content/openapi.json post /projects/{projectId}/pages openapi: 3.1.0 info: title: Weaverse Content API version: 1.0.0 description: >- Authenticated REST API for querying Weaverse-managed content (projects, pages, theme settings, languages) and for reading and writing per-locale translations. servers: - url: https://studio.weaverse.io/api/v1/content description: Production security: - bearerAuth: [] tags: - name: Projects description: List, read, rename, create, copy and delete projects. - name: Pages description: List, read, create, update and delete the pages of a project. - name: Drafts and publishing description: >- Edit page drafts, then publish, schedule, restore and manage page versions. - name: Global sections description: Read, edit and publish sections shared across pages. - name: Page settings description: Read and edit page-level settings such as SEO metadata. - name: Assignments description: Map Shopify resources and routes to Weaverse pages and templates. - name: Theme settings description: Read and update a project's theme settings. - name: Languages and localization description: List project languages and manage locales, static text and glossary. - name: Translations description: >- Read and write per-locale translations, built for external translation agents. - name: Project structure description: Manage project variants and the project hierarchy. - name: Backups and portability description: Back up, restore, export and import project content. - name: Previews and hostnames description: Create preview links and manage the hostnames a project accepts. - name: Specification description: This OpenAPI document. paths: /projects/{projectId}/pages: post: tags: - Pages summary: Create a page description: >- Creates one new page in the project. Two kinds of page are creatable: - `CUSTOM`: a bespoke merchant page addressed by a caller-chosen handle/path such as `pages/gift-shop`. Leading slashes are stripped, repeated slashes collapsed and trailing slashes removed. Starts with a blank root item unless `basedOn` is supplied. - Resource-backed types (`PRODUCT`, `COLLECTION`, `PAGE`, `BLOG`, `ARTICLE`): a per-resource override (custom template) for one Shopify resource, where `handle` is the resource handle, kept verbatim. It clones the project's shared default template for that type when one exists, otherwise it starts with a blank root item. Pass `shopifyResourceId` to bind the Shopify resource for Studio's assignment UI. Pass `basedOn` with a page id from the pages list to clone that page's layout instead. The source page must be assigned to the same project; a cross-project or unknown id returns `404 PAGE_NOT_FOUND`. This creates one page copy per call. To point many resources at a single shared template page without copying content, use `POST /projects/{projectId}/template-assignments/{pageId}`. If a live assignment already exists for the same type, handle and locale (or market), the request returns `409 CONFLICT` and creates nothing; read or edit the existing page instead. Any other type, or a missing or empty `handle`, returns `400 INVALID_PARAMS`. Legacy behaviour: a body containing `pageIds` or `handles` is treated as the bulk-delete fallback and returns a `page_delete` result. Prefer `DELETE /projects/{projectId}/pages` for deletion. Required scope: `content:write` (the bulk-delete fallback also requires `content:delete`) operationId: createPage parameters: - name: projectId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/PageCreateRequest' - type: object required: - pageIds description: >- Legacy POST-as-delete fallback. Prefer DELETE for bulk deletion. properties: pageIds: type: array items: type: string maxItems: 500 - type: object required: - handles - type description: >- Legacy POST-as-delete fallback by handles. Prefer DELETE for bulk deletion. properties: handles: type: array items: type: string maxItems: 500 type: type: string locale: type: string description: Optional. Defaults to the stored default locale. example: type: COLLECTION name: Summer Sale PLP handle: summer-sale shopifyResourceId: gid://shopify/Collection/123456789 responses: '200': description: >- Created page, or delete result when a legacy delete selector body is posted. content: application/json: schema: oneOf: - $ref: '#/components/schemas/PageCreateResponse' - type: object properties: object: type: string enum: - page_delete requested: type: integer deleted: type: integer notFound: type: integer failed: type: integer deletedHandles: type: array items: type: string notFoundHandles: type: array items: type: string failedHandles: type: array items: type: string example: object: page_create page: object: page id: clz2r8u6x0003mnop3456uvwx type: CUSTOM handle: pages/gift-shop locale: '' items: - id: 019a3c2e-5b7d-7f10-8a2b-3c4d5e6f7a81 type: main data: {} children: null updatedAt: '2026-10-20T10:30:00.000Z' meta: inherited: false sourceProjectId: clz1k8m2n0000abcd1234efgh depth: 0 '400': description: Invalid params content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or source page not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: A live page assignment already exists for this handle/type/locale content: application/json: schema: $ref: '#/components/schemas/Error' example: object: error code: CONFLICT message: 'Page already exists: COLLECTION/summer-sale' status: 409 '500': description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PageCreateRequest: type: object required: - type - handle properties: type: type: string enum: - CUSTOM - PRODUCT - COLLECTION - PAGE - BLOG - ARTICLE description: >- Page type to create. `CUSTOM` is a bespoke merchant page (blank root). The resource-backed template types (`PRODUCT`, `COLLECTION`, `PAGE`, `BLOG`, `ARTICLE`) create a per-resource override / custom template that clones the project's shared default template for that type (or `basedOn`). This creates one new page per call (a per-resource copy). To share one template page across many resources without copying, use `POST /template-assignments/{pageId}` instead. handle: type: string description: >- Page handle. For `CUSTOM`, leading slashes are stripped, repeated slashes are collapsed, and trailing slashes are removed before persistence. For resource-backed types this is the Shopify resource handle (trimmed, kept verbatim) — pass the exact handle used by the list/get/delete endpoints. name: type: string description: Optional display name. Defaults to the normalized handle. locale: type: string default: '' description: >- Optional assignment locale. Defaults to the global/default assignment (`""`). basedOn: type: string description: >- Optional 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 project's shared default template for that type is cloned when one exists; otherwise the page starts with a blank root item. shopifyResourceId: type: string description: >- Optional non-empty Shopify resource id (gid). Validated when present; persisted only for resource-backed types (PRODUCT/COLLECTION/PAGE/BLOG/ARTICLE); not stored for `CUSTOM`. additionalProperties: false PageCreateResponse: type: object properties: object: type: string enum: - page_create page: $ref: '#/components/schemas/Page' Error: type: object required: - object - code - message - status properties: object: type: string enum: - error code: type: string enum: - UNAUTHORIZED - FORBIDDEN - INSUFFICIENT_SCOPE - PROJECT_NOT_FOUND - PAGE_NOT_FOUND - STALE_PAGE - STALE_PROJECT - STALE_TRANSLATION - TRANSLATION_UNIT_NOT_FOUND - SERVICE_UNAVAILABLE - CONFLICT - PRECONDITION_REQUIRED - INVALID_PARAMS - INTERNAL_ERROR message: type: string status: type: integer details: description: >- Optional machine-readable context, for example the clashing handles of a 409 CONFLICT. Page: type: object properties: object: type: string enum: - page id: type: - string - 'null' type: type: string handle: type: string locale: type: - string - 'null' items: type: array items: $ref: '#/components/schemas/Item' updatedAt: type: - string - 'null' format: date-time meta: type: object properties: inherited: type: boolean sourceProjectId: type: string depth: type: integer seo: type: - object - 'null' description: >- The page's SEO metadata (`title`, `description`, `keywords`, `canonicalUrl`, `openGraph`, `twitter`, ...), or null when the page has none. Item: type: object description: >- A component instance. The `children` field is a JSON value encoding child items. properties: id: type: string type: type: string data: type: object description: Component props/settings children: description: Child items (JSON structure) securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: WEAVERSE_API_KEY description: >- Bearer authentication: a shop API key (WEAVERSE_API_KEY), a scoped API key, a delegated MCP OAuth token, or (translation-unit routes only) a project-bound translation agent token. Scopes: content:read — Read projects, pages, theme settings, versions, drafts and translation units. content:write — Save drafts and make non-destructive edits (page items, metadata, SEO, assignments, languages, glossary). Never publishes or deletes. content:publish — Publish drafts, schedule/reschedule/cancel publications, restore versions, publish global sections. content:delete — Delete pages, global sections, languages, static keys, override reverts; required with project:manage for project deletion. project:manage — Create/copy/delete projects, settings, variants, hierarchy, backups, restore-as-new, previews, hostname policy. translations:read — Read translation units only (no general content access). translations:write — Apply translation units only; never mutates page content. A legacy unscoped API key keeps read/write/translation baseline access and every pre-scope endpoint, but never gains publish/delete/project-manage implicitly. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.