Skip to main content

​
Overview

The Settings endpoints provide access to manage Web Stories plugin configuration. These endpoints extend the WordPress REST API Settings Controller with the web-stories/v1 namespace. Base Path: /wp-json/web-stories/v1/settings

​
Get Settings

Retrieves all registered Web Stories settings.
GET /web-stories/v1/settings
curl https://yoursite.com/wp-json/web-stories/v1/settings \
  -u "username:password"

​
Response

{
  "web_stories_archive": "default",
  "web_stories_active_publisher_logo": 123,
  "web_stories_publisher_logo_placeholder": "https://example.com/logo.png",
  "web_stories_ga_tracking_id": "UA-12345678-1",
  "web_stories_video_cache": true,
  "web_stories_data_removal": false
}

​
Available Settings

The exact settings returned depend on what’s registered in WordPress. Common Web Stories settings include:
​
web_stories_archive
string
Archive page display settingOptions: default, disabled, custom
Active publisher logo attachment IDUsed as default logo for new stories
​
web_stories_publisher_logo_placeholder
string
Publisher logo placeholder URL
​
web_stories_ga_tracking_id
string
Google Analytics tracking IDExample: UA-XXXXXXXXX-X or G-XXXXXXXXXX
​
web_stories_video_cache
boolean
Whether to enable video caching
​
web_stories_data_removal
boolean
Whether to remove all plugin data on uninstall

​
Update Settings

Updates one or more Web Stories settings.
POST /web-stories/v1/settings
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "web_stories_active_publisher_logo": 456,
    "web_stories_video_cache": false
  }'

​
Request Body

Include any settings you want to update. You can update multiple settings in a single request:
​
web_stories_archive
string
Archive page display setting
​
web_stories_active_publisher_logo
integer
Active publisher logo attachment ID
​
web_stories_ga_tracking_id
string
Google Analytics tracking ID
​
web_stories_video_cache
boolean
Enable/disable video caching
​
web_stories_data_removal
boolean
Enable/disable data removal on uninstall

​
Response

Returns all settings (same format as GET request) with updated values. 
{
  "web_stories_archive": "default",
  "web_stories_active_publisher_logo": 456,
  "web_stories_ga_tracking_id": "UA-12345678-1",
  "web_stories_video_cache": false,
  "web_stories_data_removal": false
}

​
Partial Updates

You only need to include settings you want to change. Other settings remain unchanged: 
# Update only the publisher logo
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{"web_stories_active_publisher_logo": 789}'

​
Settings Schema

The settings endpoint inherits WordPress’s REST API Settings schema. Each setting has:
  • Type: Data type (string, integer, boolean, etc.)
  • Description: Human-readable description
  • Default: Default value if not set
  • Sanitize Callback: Function to sanitize the value
  • Show in REST: Must be true for the setting to be accessible via API

​
Permissions

Settings endpoints require administrator-level permissions:
​
permissions
permission
Get Settings: Requires manage_options capabilityUpdate Settings: Requires manage_options capabilityOnly administrators can access and modify plugin settings

​
Common Errors

​
rest_forbidden
error
Status 403: You don’t have permission to manage settingsRequired capability: manage_options (typically administrator only)
​
rest_setting_setting_invalid
error
Status 400: Invalid setting name or valueThe setting name doesn’t exist or the value doesn’t match the expected type/format

​
Publisher Logo Setting

The publisher logo is a key setting used throughout Web Stories: 
# Set active publisher logo
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "web_stories_active_publisher_logo": 123
  }'
When set, this logo ID becomes the default for new stories (see Story_Post_Type.php:134 where this is used as the default meta value).

​
Analytics Integration

The Google Analytics tracking ID setting enables analytics for your web stories: 
# Set GA tracking ID
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "web_stories_ga_tracking_id": "G-XXXXXXXXXX"
  }'
Supports both Universal Analytics (UA-XXXXXXXXX-X) and Google Analytics 4 (G-XXXXXXXXXX) formats.

​
Video Cache Setting

Control whether video files are cached: 
# Enable video caching
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "web_stories_video_cache": true
  }'
When enabled, video thumbnails and metadata may be cached for better performance.

​
Data Removal Setting

Control what happens when the plugin is uninstalled: 
# Enable complete data removal on uninstall
curl -X POST https://yoursite.com/wp-json/web-stories/v1/settings \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "web_stories_data_removal": true
  }'
  • true: All stories, templates, settings, and data will be deleted when plugin is uninstalled
  • false: Stories and data are preserved after uninstall

​
Using Settings in Your Application

Settings are useful for configuring the story editor or display: 
// Fetch current settings
fetch('/wp-json/web-stories/v1/settings', {
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
})
.then(response => response.json())
.then(settings => {
  // Use settings in your app
  const publisherLogoId = settings.web_stories_active_publisher_logo;
  const gaTrackingId = settings.web_stories_ga_tracking_id;
});

// Update a setting
fetch('/wp-json/web-stories/v1/settings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce
  },
  body: JSON.stringify({
    web_stories_active_publisher_logo: newLogoId
  })
})
.then(response => response.json())
.then(settings => {
  console.log('Settings updated:', settings);
});

​
WordPress Settings API Integration

The Settings Controller integrates with WordPress’s Settings API. Settings must be:
  1. Registered via register_setting()
  2. Have show_in_rest set to true
  3. Have appropriate sanitization callbacks
  4. Be in the web-stories option group (or similar)
Only settings that meet these criteria appear in the API.

​
Best Practices

  1. Validate Input: Always validate setting values before submission
  2. Check Permissions: Ensure the current user has manage_options capability
  3. Handle Errors: Check for error responses and display appropriate messages
  4. Update Selectively: Only include settings you’re changing in POST requests
  5. Cache Responses: Settings don’t change frequently, consider caching the response
Settings work in conjunction with other Web Stories endpoints:
  • Publisher logo setting references media from the Media endpoints
  • Archive setting affects story display on the frontend
  • Analytics setting integrates with story tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us