Content API

The Weaverse Content API is a REST API that lets you read and update your page content, theme settings, and project data from any application — headless frontends, mobile apps, static site generators, AI agents, or custom integrations.

Base URL

https://studio.weaverse.io/api/v1/content

Endpoints

The endpoint reference in the sidebar is generated from the API’s OpenAPI 3.1 specification, and is refreshed each time the docs are deployed. Endpoints are grouped by area:

Area	What it covers
Projects	List, read, rename, create, copy and delete projects
Pages	List, read, create, update and delete pages
Drafts and publishing	Edit page drafts, then publish, schedule, restore and manage versions
Global sections	Read, edit and publish sections shared across pages
Page settings	Page names, handles and SEO metadata
Assignments	Map Shopify resources and routes to pages and templates
Theme settings	Read and update theme settings
Languages and localization	Locales, static text and glossary
Translations	Per-locale translations for external translation agents
Project structure	Variants and the project hierarchy
Backups and portability	Backups, restore, export and import
Previews and hostnames	Preview links and the hostnames a project accepts

Download the spec from any reference page to generate a client or load it into an API tool. The separate public discovery API exposes GET /api/public/v1/projects/:projectId/custom-pages for custom-page route metadata. It does not require a Content API key and does not filter assignments by publication state.

The Try it playground on GET reference pages sends real requests to production with the API key you enter. Write endpoints show the request only; send them from your own client.

Page endpoints capture the handle as the rest of the path. Use the exact handle returned by the pages list; custom page handles may include /, such as pages/gift-shop.

Response formats

Page and theme-settings endpoints support two output formats. The default is unchanged — existing integrations are unaffected.

Format	How to request	Output shape
`weaverse` (default)	no parameter, or `?format=weaverse`	Flat item tree with `{id, type, data, children}`
`portable-text`	`?format=portable-text`, or `Accept: application/portable-text+json`	Portable Text array, with rich-text fields converted from HTML strings to structured blocks

When both the query parameter and the Accept header are present, the query parameter wins. See Portable Text format for the mapping rules and a rendering example.

Portable Text is well-suited for multi-channel rendering (web, native, email, PDF) and for piping content into LLMs, since the structured JSON is far easier to query and reason over than HTML strings.

Authentication

All endpoints (except /openapi.json) require a Content API key. Pass it via the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://studio.weaverse.io/api/v1/content/projects

A ?apiKey= query parameter fallback exists for development, but tokens in query strings appear in server and CDN logs. Always use the Authorization header in production.

Obtaining an API key

Content API keys are provisioned per shop. Generate one from the Weaverse Dashboard → Settings.

Shop isolation

Each API key is scoped to a single Weaverse shop. Requests can only access projects that belong to that shop. Attempting to access another shop’s project returns a 403 Forbidden error.

Scopes

Scoped API keys and delegated MCP OAuth tokens carry a list of scopes. Each reference page ends with the scope it requires.

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. Translation-unit routes also accept a project-bound translation agent token.

Pagination

List endpoints (/projects and /pages) use cursor-based pagination.

Parameter	Type	Default	Description
`limit`	integer	`50`	Items per page (max `100`)
`after`	string	—	Cursor from a previous response’s `nextCursor`

Paginated response shape

{
  "object": "list",
  "data": [ ... ],
  "nextCursor": "Y2x4MWFiYzIzZGVmNDU2Z2hpag=="
}

nextCursor is null when there are no more results.
Pass nextCursor as the after parameter to fetch the next page.

Example: iterating through pages

# First page
curl -H "Authorization: Bearer $KEY" \
  "https://studio.weaverse.io/api/v1/content/projects?limit=10"

# Next page (use nextCursor from previous response)
curl -H "Authorization: Bearer $KEY" \
  "https://studio.weaverse.io/api/v1/content/projects?limit=10&after=Y2x4MWFiYzIzZGVmNDU2Z2hpag=="

Error handling

All errors follow a consistent envelope:

{
  "object": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "status": 400
}

Some errors add a details object, for example the conflicting handles of a 409. Each reference page lists the errors that endpoint returns.

Error codes

Code	HTTP Status	Description
`INVALID_PARAMS`	400	Malformed request parameters, body or cursor
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Valid key, but no access to this resource
`INSUFFICIENT_SCOPE`	403	The key lacks the scope the endpoint requires
`PROJECT_NOT_FOUND`	404	Project does not exist or was deleted
`PAGE_NOT_FOUND`	404	Page, version or assignment not found
`TRANSLATION_UNIT_NOT_FOUND`	404	A translation unit outside this project
`CONFLICT`	409	The request conflicts with current state; nothing was changed
`STALE_PAGE`	409	The page or draft changed since you read it; re-read and retry
`STALE_PROJECT`	409	The project changed since you read it; re-read and retry
`STALE_TRANSLATION`	409	The source or translation changed since you read it
`PRECONDITION_REQUIRED`	428	A required revision fence was not sent
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	A dependent service is unavailable; nothing changed

Usage tracking & billing

Every authenticated API request counts toward your plan’s usage quota. API hits share the same billing pool as storefront page views:

1 API request = 1 page view hit
Usage is tracked per project and appears in your billing dashboard
Tracking is non-blocking — it never slows down API responses
The /openapi.json endpoint is public and not tracked

Monitor your API usage in the Weaverse Studio billing dashboard to avoid unexpected overages.

Quick start

Get your API key

Obtain a Content API key from your Weaverse Studio dashboard.

List your projects

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://studio.weaverse.io/api/v1/content/projects

Fetch page content

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.weaverse.io/api/v1/content/projects/PROJECT_ID/pages/INDEX/default"

Render in your app

Use the returned items array to render page sections in any frontend framework.

TypeScript example

const BASE = 'https://studio.weaverse.io/api/v1/content'
const API_KEY = process.env.WEAVERSE_API_KEY

async function fetchPage(projectId: string, type: string, handle: string) {
  const res = await fetch(
    `${BASE}/projects/${projectId}/pages/${type}/${handle}`,
    { headers: { Authorization: ['Bearer', API_KEY].join(' ') } }
  )

  if (!res.ok) {
    const error = await res.json()
    throw new Error(`[${error.code}] ${error.message}`)
  }

  return res.json()
}

// Usage
const page = await fetchPage('clx1abc23def456ghij', 'PRODUCT', 'blue-shirt')
const customPage = await fetchPage('clx1abc23def456ghij', 'CUSTOM', 'pages/gift-shop')
console.log(page.items, customPage.items) // Arrays of section components

Next steps

List Projects

Retrieve all projects in your shop

List Pages

Browse page assignments in a project

Get Page Content

Fetch full page data with component items

Edit with Drafts

Save a draft, then publish or schedule it

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

Content API

Content API

Base URL

Endpoints

Response formats

Authentication

Obtaining an API key

Shop isolation

Scopes

Paginated response shape

Example: iterating through pages

Error handling

Error codes

Usage tracking & billing

Quick start

TypeScript example

Next steps

List Projects

List Pages

Get Page Content

Edit with Drafts

​Content API

​Base URL

​Endpoints

​Response formats

​Authentication

​Obtaining an API key

​Shop isolation

​Scopes

​Pagination

​Paginated response shape

​Example: iterating through pages

​Error handling

​Error codes

​Usage tracking & billing

​Quick start

​TypeScript example

​Next steps

List Projects

List Pages

Get Page Content

Edit with Drafts

Content API

Base URL

Endpoints

Response formats

Authentication

Obtaining an API key

Shop isolation

Scopes

Pagination

Paginated response shape

Example: iterating through pages

Error handling

Error codes

Usage tracking & billing

Quick start

TypeScript example

Next steps