Skip to main content

​
Introduction

The Web Stories for WordPress REST API provides programmatic access to create, read, update, and delete web stories, manage media, fonts, templates, and plugin settings. The API follows WordPress REST API conventions and extends the core functionality.

​
Base URL

All API endpoints are prefixed with: 
https://yoursite.com/wp-json/web-stories/v1/
The API namespace is web-stories/v1 and follows WordPress REST API standards.

​
Authentication

The Web Stories REST API uses WordPress’s built-in authentication mechanisms: For requests from the same domain (e.g., from the WordPress admin), cookie authentication is used automatically. You must include a nonce in your requests: 
fetch('/wp-json/web-stories/v1/web-story', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce
  },
  body: JSON.stringify(data)
});

​
Application Passwords

For external applications, use WordPress Application Passwords with Basic Authentication: 
curl -X GET https://yoursite.com/wp-json/web-stories/v1/web-story \
  -u "username:application-password"

​
OAuth / Third-Party Plugins

You can also use OAuth authentication plugins compatible with the WordPress REST API.

​
Common Request Headers

​
Content-Type
string
default:"application/json"
Set to application/json for POST/PUT/PATCH requests
​
X-WP-Nonce
string
Required for cookie authentication from same domain
​
Authorization
string
For Basic Auth: Basic base64(username:password)

​
Common Response Fields

All successful API responses return appropriate HTTP status codes:
  • 200 OK - Successful GET, PUT, or PATCH request
  • 201 Created - Successful POST request that creates a resource
  • 204 No Content - Successful DELETE request
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Authenticated but insufficient permissions
  • 404 Not Found - Resource does not exist
  • 500 Internal Server Error - Server error

​
Error Responses

Error responses follow the WordPress REST API error format: 
{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to create stories.",
  "data": {
    "status": 403
  }
}
​
code
string
Machine-readable error code
​
message
string
Human-readable error message
​
data
object
Additional error context

​
Common Error Codes

Error CodeDescription
rest_forbiddenUser lacks permission to perform the action
rest_invalid_paramInvalid parameter provided
rest_post_invalid_idInvalid post ID
rest_cannot_createCannot create resource
rest_cannot_editCannot edit resource
rest_cannot_deleteCannot delete resource
rest_empty_contentRequired content is missing

​
Permissions

API endpoints respect WordPress capabilities:
  • Read stories: Requires read capability
  • Create stories: Requires edit_web-stories capability
  • Edit stories: Requires edit_web-story or edit_others_web-stories capability
  • Delete stories: Requires delete_web-story or delete_others_web-stories capability
  • Manage fonts: Requires edit_web-stories capability
  • Upload media: Requires upload_files capability

​
Pagination

Collection endpoints support pagination via query parameters:
​
page
integer
default:"1"
Current page number
​
per_page
integer
default:"10"
Number of items per page (max 100)
Pagination information is included in response headers: 
X-WP-Total: 42
X-WP-TotalPages: 5

​
Embedding

Use the _embed parameter to include related resources in the response: 
curl https://yoursite.com/wp-json/web-stories/v1/web-story?_embed
This includes:
  • Author information
  • Featured media
  • Taxonomies (categories, tags)
  • Publisher logo

​
Filtering and Sorting

Most collection endpoints support filtering and sorting:
​
search
string
Search term to filter results
​
author
integer
Filter by author user ID
​
status
string
Filter by post status (publish, draft, pending, etc.)
​
orderby
string
default:"date"
Sort by field (date, title, modified, author, etc.)
​
order
string
default:"desc"
Sort order: asc or desc

​
Available Endpoints

The Web Stories REST API provides the following endpoint groups:

​
Core Endpoints (Documented)

  • Stories - Create and manage web stories (CRUD operations)
  • Media - Upload and manage media assets for stories
  • Templates - Access page templates for story creation
  • Fonts - Manage custom fonts for stories
  • Settings - Configure plugin settings

​
Additional Endpoints

The following endpoints are also available but detailed documentation is forthcoming:
  • Embed (/embed) - Fetch story metadata from URLs for embedding external stories
  • Link (/link) - Parse URL metadata for link insertion in stories
  • Hotlinking (/hotlink) - Validate and proxy external media URLs
  • Products (/products) - Search and retrieve product data for shopping features
  • Publisher Logos (/publisher-logos) - Manage publisher logo assets
  • Stories Lock (/web-story/:id/lock) - Manage story edit locks to prevent concurrent editing
  • Stories Autosaves (/web-story/:id/autosaves) - Manage story autosaves
  • Status Check (/status-check) - Check system requirements and plugin status

​
Rate Limiting

The API inherits any rate limiting configured on your WordPress installation. By default, WordPress does not impose rate limits, but you may configure them using plugins or server-level configurations.

​
Versioning

The current API version is v1. The version is included in the URL path. Future versions will be released as v2, v3, etc., maintaining backward compatibility.

​
Support

For issues or questions about the REST API:

Build docs developers (and LLMs) love

Get started for freeTalk to us