Weaverse Content API

Read and edit live Weaverse content (projects, pages, theme settings, languages) outside the Studio editor, over an authenticated REST API. Use it for bulk edits, AI/automation content pipelines, and pushing updates into a project that already exists.

• Base URL: https://studio.weaverse.io/api/v1/content
• Machine spec: GET https://studio.weaverse.io/api/v1/content/openapi.json (OpenAPI 3.1, no auth) — the authoritative contract
• Full endpoint details: references/endpoints.md. Rich-text/Portable Text details: references/portable-text.md.
• Helper script: scripts/weaverse_content_api.mjs (zero-dependency, Node 18+).

The one thing you must understand first

The Content API updates content — it does NOT create pages or projects.

PATCH .../pages/... shallow-merges data into items already on the page. Item ids that don't exist are reported as notFound and silently skipped — never created. There is no "create page" or "create project" endpoint.

So the lifecycle is:

Create initial structure   →  import a project JSON into Studio   (use generating-weaverse-project-json)
Update content afterwards   →  Content API                        (this skill)

If you need to build a brand-new storefront, page, or section, this is the wrong tool — generate import JSON with generating-weaverse-project-json and import it once. Come back here for everything after that: editing copy, swapping images, localizing, bulk edits, deletes.

When to Use

• Push AI-generated or translated copy into an existing live project
• Bulk-edit content across many pages/items
• Read current page content/items to diff or round-trip
• Delete pages in bulk
• Upload an image/video to Shopify and reference its CDN URL in a Weaverse item

Do not use it to create pages, create projects, or add new sections/blocks to a page.

Authentication

Every endpoint except openapi.json needs a bearer token:

Authorization: Bearer <WEAVERSE_API_KEY>

• Get the key from Weaverse Dashboard → Account → Content APIs.
• A token is scoped to one shop. Requests for a project owned by another shop return 403 FORBIDDEN.
• The same token also authorizes the Shopify proxy (see "Upload resources to Shopify").
• Store it in an env var (WEAVERSE_API_KEY). Never hardcode it, never pass it as a ?apiKey= query param outside local testing — query params leak into server/CDN logs.

Core update workflow

Updating content is always read ids first, then patch by id. You cannot patch blindly — you must target existing item ids.

1. Find the project — GET /projects, match by name, keep its id.
2. Pick a locale — GET /projects/:projectId/languages. Keep the isDefault: true code (e.g. en-us). You need it for the next steps.
3. Read the page — GET /projects/:projectId/pages/:type/*handle?locale=<code>. Always pass `locale`. With no locale the resolver only tries the empty locale and the legacy default en-us, so a market-first project or any project whose default locale isn't en-us returns PAGE_NOT_FOUND even though the page exists. The default weaverse format already returns every item with its `id` — that id is exactly what the patch needs, so `?meta=true` is not required (it only matters for portable-text reads).
4. Build the patch — for each item you want to change, send only the fields that change inside data (it shallow-merges, so untouched fields stay). Include the same `locale` you read with:

   {
     "locale": "en-us",
     "items": [
       { "id": "itm1", "data": { "heading": "New heading" } }
     ]
   }

1. Patch — PATCH /projects/:projectId/pages/:type/*handle (use POST if your client/proxy can't send a PATCH body). The page is resolved with the same locale rules as the read — a missing/wrong locale can hit PAGE_NOT_FOUND or patch the wrong locale's page. Max 100 items per request — chunk larger edits.
2. Check the response — { object: "page_update", updated, notFound, updatedIds, notFoundIds }. A non-empty notFoundIds means those ids aren't on the resolved page (wrong page, wrong locale, or stale ids) — re-read the page with the right locale, don't retry the same ids.

A successful patch invalidates caches and goes live through api.weaverse.io — the same path a Studio save takes.

Page addressing

Pages are addressed by Prisma page type + handle:

INDEX, PRODUCT, ALL_PRODUCTS, COLLECTION, COLLECTION_LIST, PAGE, BLOG,
ARTICLE, CART, CUSTOMER, NOT_FOUND, PASSWORD, SEARCH, CUSTOM

• Singletons (INDEX, ALL_PRODUCTS, COLLECTION_LIST, CART, CUSTOMER, NOT_FOUND, PASSWORD, SEARCH) — one page per project, omit the handle.
• CUSTOM — addressed by its path (the splat may contain slashes, e.g. blogs/news).
• Templated (PRODUCT, COLLECTION, PAGE, BLOG, ARTICLE) — keep a shared default template at the empty handle, so a missing handle is rejected (it won't silently edit the template). Pass the real handle.

Locale always matters. On reads/updates, always pass a real locale code (from List languages). In list-pages responses, a row's locale may be null for market-first projects (rows are keyed by market, not locale) — don't echo null back; pass a real code and let resolution map it to the market (e.g. locale=en-us resolves market us).

See references/endpoints.md for the full endpoint list, query params, and response shapes.

Upload resources to Shopify

The Content API itself has no upload endpoint. To get media into a Weaverse item, upload it to Shopify first, then reference the returned CDN URL.

Upload goes through the Weaverse Shopify proxy, which accepts the same Weaverse token:

POST https://studio.weaverse.io/api/admin-graphql
Authorization: Bearer <WEAVERSE_API_KEY>
Content-Type: application/json

The body is a normal Shopify Admin GraphQL request ({ "query": "...", "variables": {...} }). Upload is the standard two-step Shopify flow:

1. stagedUploadsCreate → get a url + parameters (a presigned target) and a resourceUrl.
2. Upload the file bytes to that staged url with the returned parameters (multipart POST, not through the proxy).
3. fileCreate with originalSource: <resourceUrl> → Shopify ingests it and returns the permanent CDN file.
4. Read back the file's image.url / sources and put that CDN URL into the Weaverse item data via the update workflow above.

Reference implementation in the builder repo: app/backend/admin/file.server.ts (generateStagedUploadLinks → stagedUploadsCreate, then fileCreate). When in doubt, mirror its mutations and field selections.

Alternatively, when a connected Shopify MCP is available, its image-upload / graphql_mutation tools do the same job without the proxy. Use whichever is connected.

Helper script

scripts/weaverse_content_api.mjs wraps auth and the common calls. It reads WEAVERSE_API_KEY from the environment.

export WEAVERSE_API_KEY=...

node scripts/weaverse_content_api.mjs projects
node scripts/weaverse_content_api.mjs languages <projectId>
node scripts/weaverse_content_api.mjs theme <projectId>
node scripts/weaverse_content_api.mjs pages <projectId> [type]
node scripts/weaverse_content_api.mjs page <projectId> <type> [handle] [locale]   # reads with ?locale
node scripts/weaverse_content_api.mjs update <projectId> <type> <handle> <patch.json>
node scripts/weaverse_content_api.mjs delete <projectId> <type> <handle...>

Use it to inspect a project quickly and to apply patch files. For anything the script doesn't cover, call the REST endpoints directly or read openapi.json.

Red Flags

• Trying to create a page/project/section via the API — it can't. Use generating-weaverse-project-json + import for new structure.
• Patching without reading ids first — you must target existing item ids. Read the page first (with the right locale); the default weaverse read already includes every item id, so you do not need ?meta=true.
• Omitting `locale` on a page read/update — with no locale the resolver only tries the empty locale and legacy en-us, so non-en-us or market-first projects return PAGE_NOT_FOUND even when the page exists. Always pass a real locale from List languages.
• "My published edit is missing from the API" — silent wrong-locale page (not a 404). Content is stored per locale (PageAssignment keyed by projectId, locale, type, handle). When a merchant edits/publishes with a market locale selected (e.g. en-us), the change saves to the en-us assignment, not the base locale "". Because locale defaults to "", a request like …/pages/PRODUCT/default (no ?locale) can succeed (200) but return the base-locale assignment — a different, often empty/stale page — so the edit looks "missing" even though it published fine. This is distinct from PAGE_NOT_FOUND: the request works, it just returns the wrong locale's page. Fix: always pass ?locale=<market> (e.g. en-us). To find which locale a product/page uses: Studio top-bar template dropdown (shows active template + "Assigned to N products") with the market/locale selector beside it; or GET /pages (locale per row); or read data-weaverse-template-id from the live storefront HTML. Verified live (PwC/Westside, project lzum53gvsbhehjr3in906myu): edit lived on locale=en-us (active, freshly published), base locale="" was the stale one the no-locale call returned.
• Echoing back `locale: null` — list-pages rows can be null for market-first projects. Don't send null; pass a real code and let resolution map it to the market.
• Adding `?meta=true` for normal edits — it only affects portable-text reads (where it restores _weaverse.id). On a weaverse-format read it changes nothing.
• Ignoring `notFoundIds` in the response — it means your ids aren't on the resolved page (wrong page, wrong locale, or stale ids). Re-read with the right locale, don't retry.
• Sending more than 100 items in one update (or 500 targets in one delete) — chunk the request.
• Editing a templated type with an empty handle — rejected by design. Pass the real handle.
• Hardcoding the token or using `?apiKey=` — use Authorization: Bearer from an env var.
• Replacing whole `data` objects — updates shallow-merge. Send only changed fields; don't resend the entire data and risk wiping nested values you didn't read.
• Putting a non-Shopify URL into a media field after "upload" — finish the fileCreate step and use the returned Shopify CDN URL, not the staged/temporary resourceUrl.

Related skills

• generating-weaverse-project-json — creates the import JSON that establishes the structure this API then updates. The item ids you patch here come from that JSON (or from a page read back with the right locale).
• cloning-websites-to-weaverse / figma-to-weaverse — produce the section plan that feeds the JSON generator.