curl --request POST \
  --url https://studio.weaverse.io/api/v1/content/projects/{projectId}/hierarchy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "op": "create-variant",
  "name": "Staging"
}
'

{
  "object": "page_override_reverted",
  "success": true,
  "deletedAssignmentId": "clz8r5t6u0010pa02home0001",
  "restoredInheritance": true,
  "parentPageId": "clz8q1m2n0002pg01home0001"
}

{
  "object": "variant_created",
  "variant": {
    "project": {
      "id": "clz8p2k0q0009ab12cd34stg01",
      "weaverseShopId": "clz7s0h1p0000shop0000001",
      "name": "Staging",
      "publishedTimestamp": null,
      "createdAt": "2026-10-15T11:40:02.000Z",
      "updatedAt": "2026-10-15T11:40:02.000Z",
      "deletedAt": null,
      "inheritTheme": true,
      "marketFirstEnabled": true,
      "parentProjectId": "clz8p2k0q0001ab12cd34ef56",
      "variantDescription": "Pre-release checks"
    },
    "clonedPagesCount": 0
  }
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "CONFLICT",
  "message": "No live inherited page would replace this override for its market/locale; nothing was deleted",
  "status": 409
}

Project structure

Manage variants and page overrides

Runs one hierarchy operation, selected by op. A variant is a child project that inherits pages (and optionally the theme) from its parent; customizing a page gives the variant its own override. All operations take effect immediately.

Operations:

create-variant: creates a variant of this project named name (1-100 characters), with optional variantDescription (max 500) and inheritTheme (default true). contentStrategy is empty (default; the variant inherits every page) or clone-all (copies every page into the variant). Returns 201 with the new project and clonedPagesCount.
link-parent: makes this project a variant of parentProjectId (same shop), with optional variantDescription and inheritTheme. Hierarchies are at most two levels deep.
detach-parent (confirm equal to the projectId): turns this variant into an independent project, copying inherited content first. Returns pagesCopied.
customize-page: copies a page inherited from the parent into this variant as an override. pageAssignmentId is the parent’s assignment id.
revert-page (content:delete, confirm equal to pageAssignmentId): deletes this variant’s override so the page inherits from the parent again. Only allowed when the parent would actually serve a live page for the override’s exact market or locale; otherwise it returns 409 CONFLICT and the override is kept.

A refused transition (maximum depth, project name already taken, circular link, not a variant, page already customized) returns 409 CONFLICT and changes nothing. A wrong confirm value returns 400 INVALID_PARAMS.

Required scope: project:manage (all operations); revert-page also needs content:delete

POST

projects

{projectId}

hierarchy

curl --request POST \
  --url https://studio.weaverse.io/api/v1/content/projects/{projectId}/hierarchy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "op": "create-variant",
  "name": "Staging"
}
'

{
  "object": "page_override_reverted",
  "success": true,
  "deletedAssignmentId": "clz8r5t6u0010pa02home0001",
  "restoredInheritance": true,
  "parentPageId": "clz8q1m2n0002pg01home0001"
}

{
  "object": "variant_created",
  "variant": {
    "project": {
      "id": "clz8p2k0q0009ab12cd34stg01",
      "weaverseShopId": "clz7s0h1p0000shop0000001",
      "name": "Staging",
      "publishedTimestamp": null,
      "createdAt": "2026-10-15T11:40:02.000Z",
      "updatedAt": "2026-10-15T11:40:02.000Z",
      "deletedAt": null,
      "inheritTheme": true,
      "marketFirstEnabled": true,
      "parentProjectId": "clz8p2k0q0001ab12cd34ef56",
      "variantDescription": "Pre-release checks"
    },
    "clonedPagesCount": 0
  }
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "status": 123,
  "details": "<unknown>"
}

{
  "object": "error",
  "code": "CONFLICT",
  "message": "No live inherited page would replace this override for its market/locale; nothing was deleted",
  "status": 409
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

projectId

string

required

Query Parameters

analyzeParent

string

Body

application/json

Option 1
Option 2
Option 3
Option 4
Option 5

any

required

name

string

required

variantDescription

string

inheritTheme

boolean

contentStrategy

enum<string>

Available options:

empty,

clone-all

Response

Operation result

The response is of type object.

Get started

Projects

Pages

Assignments

Theme settings

Languages and localization

Specification

Translations

Drafts and publishing

Global sections

Page settings

Project structure

Backups and portability

Previews and hostnames

Manage variants and page overrides

Authorizations

Path Parameters

Query Parameters

Body

Response