> ## 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/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Import an export file into this project

> Destructive. Overwrites live content of this project in place, through the same import core the dashboard uses (format-version check, preflight of every page before the first write, theme then pages, cache reset). Writes go live immediately, bypassing drafts, and override mode replaces existing pages. Back up first with `POST /projects/{projectId}/backups`.

Send `multipart/form-data` with:

- `file`: an export JSON from `GET /projects/{projectId}/export` (max 50 MB).
- `options`: a JSON string `{ "importTheme": boolean, "importPages": boolean, "pagesImportMode": "override" | "skip", "selectedPageIds"?: string[] }`. `override` replaces pages whose assignment already exists; `skip` keeps them.
- `confirm`: must equal the `projectId` in the path.

Limits and errors:
- The whole multipart body is byte-capped while streaming (file cap plus 64 KiB of framing); a second file part is rejected.
- 400 for an invalid file, options or confirmation; the import core's reason is in `details.importCode` (for example `INVALID_FILE`, `FILE_TOO_LARGE`, `PARSE_ERROR` for `options` that are not JSON, `INVALID_OPTIONS` for `options` that fail validation).
- A 200 can still report per-part failures: check `results.theme.success`, `results.pages.errors` and `results.pages.skippedInfo`.

Every key issued since scopes exist (including a baseline-only key) must use this route. The legacy `/api/projects/import` admits only pre-scope keys and authenticated merchant sessions, never narrow agent or MCP bearers.

Required scopes: `project:manage`, `content:publish` and `content:delete` (all three)



## OpenAPI

````yaml https://studio.weaverse.io/api/v1/content/openapi.json post /projects/{projectId}/import
openapi: 3.1.0
info:
  title: Weaverse Content API
  version: 1.0.0
  description: >-
    Authenticated REST API for reading and editing Weaverse-managed content
    (projects, pages, drafts, global sections, theme settings, languages) and
    for reading and writing per-locale translations.


    ## Authentication


    Send a bearer token in the `Authorization` header: a shop API key
    (`WEAVERSE_API_KEY`), a scoped API key or a delegated MCP OAuth token.
    Translation-unit routes also accept a project-bound translation agent token.
    Each operation's description ends with the scope it requires.


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `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 or cancel
    publications, restore versions, publish global sections |

    | `content:delete` | Delete pages, global sections, languages and static
    keys, and revert overrides. Project deletion also needs `project:manage` |

    | `project:manage` | Create, copy and delete projects; settings, variants,
    hierarchy, backups, restore as new, previews and hostname policy |

    | `translations:read` | Read translation units only, with no general content
    access |

    | `translations:write` | Apply translation units only; never changes page
    content |


    A legacy API key without scopes keeps read, write and translation access and
    every endpoint that existed before scopes, but never gains publish, delete
    or project management.
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}/import:
    summary: >-
      Import an export file into this project (project:manage + content:publish
      + content:delete)
    description: >-
      Overwrites live content in place through the dashboard import core.
      multipart/form-data: file (export JSON, max 50MB), options (JSON string:
      importTheme, importPages, pagesImportMode override|skip,
      selectedPageIds?), confirm (= projectId). The whole multipart body is
      byte-capped while streaming (file cap + 64 KiB framing); a second file
      part is rejected. Every key issued since scopes exist (including a
      baseline-only key) must use this route: the legacy /api/projects/import
      admits only pre-scope keys and authenticated merchant sessions, never
      forged preview identity or narrow agent/MCP bearers.
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Backups and portability
      summary: Import an export file into this project
      description: >-
        Destructive. Overwrites live content of this project in place, through
        the same import core the dashboard uses (format-version check, preflight
        of every page before the first write, theme then pages, cache reset).
        Writes go live immediately, bypassing drafts, and override mode replaces
        existing pages. Back up first with `POST /projects/{projectId}/backups`.


        Send `multipart/form-data` with:


        - `file`: an export JSON from `GET /projects/{projectId}/export` (max 50
        MB).

        - `options`: a JSON string `{ "importTheme": boolean, "importPages":
        boolean, "pagesImportMode": "override" | "skip", "selectedPageIds"?:
        string[] }`. `override` replaces pages whose assignment already exists;
        `skip` keeps them.

        - `confirm`: must equal the `projectId` in the path.


        Limits and errors:

        - The whole multipart body is byte-capped while streaming (file cap plus
        64 KiB of framing); a second file part is rejected.

        - 400 for an invalid file, options or confirmation; the import core's
        reason is in `details.importCode` (for example `INVALID_FILE`,
        `FILE_TOO_LARGE`, `PARSE_ERROR` for `options` that are not JSON,
        `INVALID_OPTIONS` for `options` that fail validation).

        - A 200 can still report per-part failures: check
        `results.theme.success`, `results.pages.errors` and
        `results.pages.skippedInfo`.


        Every key issued since scopes exist (including a baseline-only key) must
        use this route. The legacy `/api/projects/import` admits only pre-scope
        keys and authenticated merchant sessions, never narrow agent or MCP
        bearers.


        Required scopes: `project:manage`, `content:publish` and
        `content:delete` (all three)
      operationId: importProject
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - options
                - confirm
              properties:
                file:
                  type: string
                  format: binary
                options:
                  type: string
                confirm:
                  type: string
      responses:
        '200':
          description: Import results
          content:
            application/json:
              schema:
                type: object
              example:
                object: project_import
                projectId: clz8k2m4n0001qwer7tyu8iop
                results:
                  theme:
                    success: true
                    message: Theme settings imported successfully
                  pages:
                    success: true
                    imported: 4
                    skipped: 1
                    total: 5
                    errors: []
                    skippedInfo:
                      - 'Replaced 1 templates: "Homepage"'
                  cleanup: null
        '400':
          description: >-
            Invalid file, options or confirmation (details.importCode:
            PARSE_ERROR for options that are not JSON, INVALID_OPTIONS for
            options that fail validation)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                object: error
                code: INVALID_PARAMS
                message: >-
                  "confirm" must be "clz8k2m4n0001qwer7tyu8iop" for this
                  destructive operation
                status: 400
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Foreign project or missing scope (INSUFFICIENT_SCOPE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found (never discloses other tenants)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: File too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Not multipart/form-data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: WEAVERSE_API_KEY
      description: >-
        Bearer token: a shop API key (`WEAVERSE_API_KEY`), a scoped API key or a
        delegated MCP OAuth token; translation-unit routes also accept a
        project-bound translation agent token. Each operation lists the scope it
        requires; the scope table is in the API description.

````

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