API Reference

Pebble provides PHP endpoints for content management and a JavaScript API for frontend integration.

PHP Endpoints

All endpoints are located in your pebble/ directory. POST endpoints require CSRF token validation.

Authentication

POST pebble/auth.php

Content Loading

GET pebble/load.php (Public - no auth required)

Content Saving

POST pebble/save.php (Auth required)

Image Upload

POST pebble/upload.php (Auth required)

Accepts multipart form data with an image file. Automatically:

• Validates file type (JPEG, PNG, GIF, WebP)
• Resizes to max 2000x2000px while maintaining aspect ratio
• Compresses for web (JPEG 75%, PNG level 9)
• Returns the new image path

Content Deletion

POST pebble/delete.php (Auth required)

Deleted content is moved to trash, not permanently removed.

Control Panel

POST pebble/admin.php (Auth required)

Backup Management

POST pebble/backup.php (Auth required)

Pro Endpoints

Zone Content

GET pebble/pro/zone-load.php (Public)

Load zone blocks as JSON with Quill Delta format.

POST pebble/pro/zone-save.php (Auth + License required)

Save zone blocks. Requires valid Pro license.

Repeatable Content

GET pebble/pro/repeatable.php?action=load&id=:id

Load repeatable items array.

POST pebble/pro/repeatable.php (Auth + License required)

Save repeatable items. Requires valid Pro license.

JavaScript API

The global window.Pebble object provides access to core functionality:

// Check authentication status
Pebble.isAuthenticated()  // Returns boolean

// Get CSRF token for custom requests
Pebble.getCSRFToken()     // Returns token string

// Show notification toast
Pebble.showNotification(message, type)  // type: 'success', 'error', 'info'

// Save content programmatically
Pebble.save(id, html, shared)  // Returns Promise

// Load content programmatically
Pebble.load(id, shared)  // Returns Promise

Data Attributes

Core Pebbles

Zones (Pro)

Available toolbar options: bold, italic, underline, h2, h3, list, link

Repeatables (Pro)

Supported Pebble Types in Repeatables

Inside repeatable items, you can use any pebble type:

• data-pebble="id" - Plain text (default)
• data-pebble-type="rich" - Rich text with bold/italic/link
• data-pebble-type="image" - Uploadable images
• data-pebble-type="link" - Editable link (text + URL)

Configuration Reference

All settings are defined in config.php. Key settings:

Authentication

Pro Features

Other Settings

Storage Structure

Pebble stores content in flat files under pebble/data/:

pebble/data/
  content/     # Page-specific content (id.html)
  shared/      # Site-wide content (id.html)
  zones/       # Zone blocks (id.json)
  repeatable/  # Repeatable arrays (id.json)
  uploads/     # Optimized images
  trash/       # Deleted items with timestamps
  backups/     # ZIP backup files

CSRF Protection

All POST requests that modify data require a CSRF token. The token is:

• Generated per session (32 bytes, cryptographically random)
• Validated with timing-safe comparison
• Required on: save, delete, backup, and admin operations

Get the token from your session or via JavaScript:

const token = Pebble.getCSRFToken();

// Include in your requests
fetch('/pebble/save.php', {
  method: 'POST',
  body: JSON.stringify({
    id: 'my-pebble',
    html: 'New content',
    csrf_token: token
  })
});

Next Steps

• Usage Guide - Learn how to use data attributes
• Security - Authentication and protection
• Troubleshooting - Common issues