Skip to main content

​
Overview

The Page Template endpoints provide access to pre-designed templates that users can use as starting points for creating new web stories. Templates are stored as a custom post type. Base Path: /wp-json/web-stories/v1/web-story-page-template

​
List Templates

Retrieves a collection of available page templates.
GET /web-stories/v1/web-story-page-template
curl https://yoursite.com/wp-json/web-stories/v1/web-story-page-template

​
Query Parameters

​
context
string
default:"view"
Scope: view, edit, or embed
​
page
integer
default:"1"
Current page number
​
per_page
integer
default:"10"
Maximum number of items (max 100)
​
search
string
Search templates by title
​
orderby
string
default:"date"
Sort by: date, title, modified
​
order
string
default:"desc"
Sort order: asc or desc
​
_embed
boolean
default:"false"
Include embedded resources
​
_web_stories_envelope
boolean
default:"false"
Wrap response in envelope for preloading

​
Response

[
  {
    "id": 789,
    "date": "2024-03-15T10:30:00",
    "slug": "modern-lifestyle-template",
    "status": "publish",
    "type": "web-story-page-template",
    "link": "https://example.com/web-story-page-template/modern-lifestyle-template/",
    "title": {
      "rendered": "Modern Lifestyle"
    },
    "content": {
      "rendered": "<html>...</html>",
      "protected": false
    },
    "author": 1,
    "featured_media": 790,
    "story_data": {
      "version": 1,
      "pages": [
        {
          "id": "page-1",
          "backgroundColor": {
            "color": {
              "r": 255,
              "g": 255,
              "b": 255
            }
          },
          "elements": [
            {
              "id": "element-1",
              "type": "text",
              "x": 50,
              "y": 100,
              "width": 200,
              "height": 50,
              "content": "<span>Sample Text</span>"
            }
          ]
        }
      ]
    },
    "_links": {
      "self": [
        {"href": "https://example.com/wp-json/web-stories/v1/web-story-page-template/789"}
      ]
    }
  }
]

​
Get Template

Retrieves a single page template by ID.
GET /web-stories/v1/web-story-page-template/:id
curl https://yoursite.com/wp-json/web-stories/v1/web-story-page-template/789

​
Path Parameters

​
id
integer
required
Unique identifier for the template

​
Response Fields

​
id
integer
Unique identifier for the template
​
date
string
Creation date in ISO 8601 format
​
slug
string
URL-friendly slug
​
status
string
Template status (typically publish)
​
title
object
Template title
​
content
object
Template HTML content
​
story_data
object
JSON structure of the template
​
author
integer
Template creator user ID
​
featured_media
integer
Featured media attachment ID (template preview image)

​
Create Template

Creates a new page template. Requires elevated permissions.
POST /web-stories/v1/web-story-page-template
curl -X POST https://yoursite.com/wp-json/web-stories/v1/web-story-page-template \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "title": "My Custom Template",
    "status": "publish",
    "content": "<html>...</html>",
    "story_data": {
      "version": 1,
      "pages": [...]
    },
    "featured_media": 791
  }'

​
Request Body

​
title
string
required
Template title
​
content
string
required
Template HTML content
​
story_data
object
required
JSON template structure with pages and elements
​
status
string
default:"publish"
Template status: publish, draft, pending
​
featured_media
integer
Preview image attachment ID

​
Response

Returns the created template object with HTTP 201 status.

​
Update Template

Updates an existing page template.
PUT /web-stories/v1/web-story-page-template/:id
curl -X PUT https://yoursite.com/wp-json/web-stories/v1/web-story-page-template/789 \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "title": "Updated Template Name",
    "story_data": {...}
  }'

​
Path Parameters

​
id
integer
required
Unique identifier for the template

​
Request Body

Accepts the same parameters as Create Template. All fields are optional.
Like stories, content and story_data should be updated together.

​
Response

Returns the updated template object with HTTP 200 status.

​
Delete Template

Deletes a page template.
DELETE /web-stories/v1/web-story-page-template/:id
curl -X DELETE https://yoursite.com/wp-json/web-stories/v1/web-story-page-template/789?force=true \
  -u "username:password"

​
Path Parameters

​
id
integer
required
Unique identifier for the template

​
Query Parameters

​
force
boolean
default:"false"
Whether to bypass trash and force deletion

​
Response

{
  "deleted": true,
  "previous": {
    "id": 789,
    "title": {
      "rendered": "Deleted Template"
    }
  }
}

​
Using Templates to Create Stories

Templates can be used as a starting point when creating new stories: 
# 1. Fetch a template
curl https://yoursite.com/wp-json/web-stories/v1/web-story-page-template/789

# 2. Use the template's story_data to create a new story
curl -X POST https://yoursite.com/wp-json/web-stories/v1/web-story \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "title": "My Story from Template",
    "status": "draft",
    "content": "<html>...</html>",
    "story_data": {...template_story_data...}
  }'

​
Permissions

Page template endpoints require specific permissions:
​
get_items_permissions_check
permission
List/Get Templates: Requires edit_web-stories capabilityUsers must have permission to edit web stories to access templates
​
create_item_permissions_check
permission
Create Templates: Requires edit_web-stories capabilityOnly users who can edit web stories can create templates
​
update_item_permissions_check
permission
Update Templates: Requires edit_web-story or edit_others_web-stories capability
​
delete_item_permissions_check
permission
Delete Templates: Requires delete_web-story or delete_others_web-stories capability

​
Template Schema

Templates follow the same data structure as stories but are meant to be reusable starting points. Key differences:
  • Templates don’t include user-specific content
  • Template story_data contains placeholder content
  • Templates are published and shared across all users
  • Templates typically have preview images as featured media

​
Common Errors

​
rest_forbidden_context
error
Status 403: You are not allowed to edit page templatesRequired capability: edit_web-stories
​
rest_post_invalid_id
error
Status 404: Template with the specified ID does not exist

​
Schema Differences from Stories

The Page Template endpoint extends Stories_Base_Controller but has some schema modifications:
  • Removes permalink_template property (not needed for templates)
  • Removes generated_slug property (not needed for templates)
  • Maintains story_data structure identical to stories

Build docs developers (and LLMs) love

Get started for freeTalk to us