Runtime API

The Cellpy custom element interface and REST API reference.

Authentication

REST API requests require a Bearer token.

curl https://api.cellpy.com/v1/blocks \
  -H "Authorization: Bearer your_token_here"

Custom element

The <cellpy-block> HTML custom element — attributes, CSS variables, and events.

<!-- On the element -->
<cellpy-block slug="pricing" style="--cellpy-primary: #e11d48;"></cellpy-block>

<!-- On an ancestor (e.g. your brand theme) -->
<div style="--cellpy-primary: #6366f1;">
  <cellpy-block slug="hero-main"></cellpy-block>
  <cellpy-block slug="cta-footer"></cellpy-block>
</div>

JavaScript API

Imperative control of cellpy-block elements from JavaScript.

const block = document.querySelector('cellpy-block[slug="pricing"]')

// Force a fresh fetch from the CDN, bypassing cache
await block.refresh()

// Get info about the currently loaded block
const info = block.blockInfo
// → { blockId: "abc123", version: 3, slug: "pricing", env: "production" }

// Listen for load events
block.addEventListener('cellpy:load', (e: CustomEvent) => {
  console.log('Block loaded:', e.detail.blockId)
})

// Switch environments at runtime
block.setAttribute('env', 'staging')

REST — Blocks

Manage blocks in your Workspace programmatically.

List all blocks in your Workspace. Supports ?status=pending|saved|archived and ?q= for keyword search.

Get a single block by ID. Returns full HTML, CSS, metadata, and version history.

Create a new block in your Workspace (equivalent to 'Push to Workspace').

Update an existing block's HTML, CSS, name, or status.

Archive a block. Archived blocks are not deleted — they can be restored.

# Create a block (push to Workspace)
curl -X POST https://api.cellpy.com/v1/blocks \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pricing-cards",
    "html": "<div class=\"card\">...</div>",
    "css": ".card { padding: 24px; }",
    "environment": "staging"
  }'

# Response
{
  "id": "blk_x7qP2kLm",
  "name": "pricing-cards",
  "status": "pending",
  "environment": "staging",
  "createdAt": "2026-06-04T10:00:00Z"
}

REST — Containers

Manage container assignments and publishing.

List all containers in your organization.

Get a container's current state — assigned block, live version, and embed metadata.

Update the assigned block and/or trigger a publish to production.

# Assign a block and publish to production
curl -X PATCH https://api.cellpy.com/v1/containers/pricing \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "blockId": "blk_x7qP2kLm",
    "publish": true
  }'

# Response
{
  "slug": "pricing",
  "blockId": "blk_x7qP2kLm",
  "liveVersion": 1,
  "publishedAt": "2026-06-04T10:05:00Z",
  "cdnUrl": "https://cdn.cellpy.com/b/blk_x7qP2kLm/v1.js"
}

REST — Tokens

Manage API tokens programmatically.

List all API tokens for your account (secrets are never returned after creation).

Create a new API token. The secret is returned only once in the response.

Revoke a token immediately. All requests using that token will return 401.

CDN delivery

How blocks are served to end users.

# Fetch block metadata (no auth required for public containers)
GET https://cdn.cellpy.com/c/:container-slug/meta.json

# Response
{
  "slug": "pricing",
  "blockId": "blk_x7qP2kLm",
  "version": 3,
  "bundleUrl": "https://cdn.cellpy.com/b/blk_x7qP2kLm/v3.js",
  "updatedAt": "2026-06-04T10:05:00Z"
}

Errors & rate limits

{
  "error": "validation_failed",
  "message": "Block name is required",
  "errors": [
    { "field": "name", "message": "Required" }
  ]
}