---
title: "Run a project lifecycle operation"
method: POST
path: "/projects"
tags: ["Projects"]
---

# Run a project lifecycle operation

`POST /projects`

## Request

- Base URL: `https://studio.weaverse.io/api/v1/content`
- URL: `https://studio.weaverse.io/api/v1/content/projects`
- Auth: HTTP bearer

Shop-scoped project lifecycle. The body's `op` field selects the operation:

- `create`: creates a project in the caller's shop. `name` is required (1-100 characters). Set `config.themeName` to seed it from a theme; omit it or pass `blank` for a blank project with generated storefront pages. If the theme seed fails, a blank project is created instead and the response carries a `warning`. Returns `201` with `object: "project_created"`.
- `copy`: clones `sourceProjectId` into the caller's shop. The source must be this shop's own project or a public demo-store project; any other shop's project returns `404`. The clone runs in the background: the response is `202` with `object: "project_copy_started"` and the `targetProjectId`. Observe completion by listing the target project's pages. `name` defaults to `Copy of <source name>`.
- `delete`: soft-deletes `projectId` (a backup is taken first) and purges its caches. `confirm` must equal the `projectId`, otherwise `400`. A project that still has variant (child) projects returns `409 CONFLICT` (`HAS_VARIANTS`). Returns `200` with `object: "project_deleted"`.
- `set-settings`: revision-fenced write of non-secret settings (`name`, `defaultLocale`). Pass the project's current `revision` (from `GET /projects/{projectId}`) as `expectedUpdatedAt`; if the project changed since, the request returns `409 STALE_PROJECT` and writes nothing. `defaultLocale` is the full Hydrogen i18n object Studio stores (`label`, `language`, `country`, `pathPrefix`). Returns `200` with `object: "project_settings_updated"` and the new `projectRevision`.
- `purge-cache`: the Studio "Clear cache" action. Invalidates the project's caches without touching content. Returns `200` with `object: "cache_purged"`.

Every operation other than `create` and `copy` must target a live project owned by the caller's shop; otherwise `404`.

Required scope: `project:manage` (`delete` also requires `content:delete`)

## Request body

- union
  - object
    - `op` 'create', required
    - `name` string
    - `projectId` string: Optional client-chosen id
    - `config` object
      - `themeName` string
  - object: Copy a project into the caller shop. Source: this shop's own project or a public demo-store project (same policy as the dashboard); any other shop's project is 404. The clone runs in the background (202 + targetProjectId); completion is observed by listing the target's pages.
    - `op` 'copy', required
    - `sourceProjectId` string, required
    - `name` string
  - object
    - `op` 'delete', required
    - `projectId` string, required
    - `confirm` string, required: Must equal the projectId
  - object
    - `op` 'set-settings', required
    - `projectId` string, required
    - `expectedUpdatedAt` string, date-time, required
    - `name` string
    - `defaultLocale` object: Full Hydrogen i18n default locale, the shape Studio stores.
      - `label` string, required
      - `language` string, required
      - `country` string, required
      - `pathPrefix` string, required
  - object: The Studio "Clear cache" action: invalidate this project's caches. project:manage.
    - `op` 'purge-cache', required
    - `projectId` string, required

## Response `200`

Operation result

- object

## Other responses

- `201`: Created (create/copy-restore targets)
- `202`: Copy started; poll the target project
- `400`: Invalid body
- `401`: Missing or invalid credentials
- `403`: Foreign project or missing scope (INSUFFICIENT_SCOPE)
- `404`: Not found (never discloses other tenants)
- `409`: STALE_PROJECT or HAS_VARIANTS

---

[API](https://skmtc.dev/weaverse/apis/weaverse-content-api.md) - [All operations](https://skmtc.dev/weaverse/apis/weaverse-content-api/llms.txt) - [OpenAPI document](https://skmtc.dev/weaverse/apis/weaverse-content-api/revisions/d189794169bb?raw)