Skip to main content

​
Content API

The Weaverse Content API is a read-only REST API that lets you access your page content, theme settings, and project data from any application — headless frontends, mobile apps, static site generators, or custom integrations.
The Content API is currently read-only (GET requests). Write endpoints are planned for a future release.

​
Base URL

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

​
Endpoints

MethodPathDescription
GET/projectsList all projects
GET/projects/:projectId/pagesList page assignments
GET/projects/:projectId/pages/:type/:handleGet page content
GET/projects/:projectId/theme-settingsGet theme settings
GET/openapi.jsonOpenAPI 3.1 specification

​
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.

​
Scoping

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.

​
Pagination

List endpoints (/projects and /pages) use cursor-based pagination.
ParameterTypeDefaultDescription
limitinteger50Items per page (max 100)
afterstring—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
}

​
Error codes

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Valid key, but no access to this resource
PROJECT_NOT_FOUND404Project does not exist or was deleted
PAGE_NOT_FOUND404Page assignment not found (after locale fallback)
INVALID_PARAMS400Malformed request parameters or cursor
INTERNAL_ERROR500Unexpected server error

​
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

1

Get your API key

Obtain a Content API key from your Weaverse Studio dashboard.
2

List your projects

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

Fetch page content

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

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}` } }
  )

  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')
console.log(page.items) // Array 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

Get Theme Settings

Retrieve theme design tokens and configuration