Media Endpoints

Overview

The Media endpoints provide access to upload and manage images, videos, and other media assets used in web stories. This extends the WordPress Attachments API with web stories-specific functionality. Base Path: /wp-json/web-stories/v1/media

List Media

Retrieves a collection of media items.

GET /web-stories/v1/media

curl https://yoursite.com/wp-json/web-stories/v1/media

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)

string

Search media by title or filename

author

integer

Filter by uploader user ID

parent

integer

Filter by parent post ID

media_type

string

Filter by media type: image, video

mime_type

string

Filter by MIME type (e.g., image/jpeg, video/mp4)

orderby

string

default:"date"

Sort by: date, title, modified, relevance

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": 456,
    "date": "2024-03-15T10:30:00",
    "slug": "awesome-image",
    "type": "attachment",
    "link": "https://example.com/awesome-image/",
    "title": {
      "rendered": "Awesome Image"
    },
    "author": 1,
    "caption": {
      "rendered": "A beautiful sunset"
    },
    "alt_text": "Sunset over mountains",
    "media_type": "image",
    "mime_type": "image/jpeg",
    "media_details": {
      "width": 1920,
      "height": 1080,
      "file": "2024/03/sunset.jpg",
      "filesize": 245632,
      "sizes": {
        "thumbnail": {
          "file": "sunset-150x150.jpg",
          "width": 150,
          "height": 150,
          "mime_type": "image/jpeg",
          "source_url": "https://example.com/wp-content/uploads/2024/03/sunset-150x150.jpg"
        },
        "medium": {
          "file": "sunset-300x169.jpg",
          "width": 300,
          "height": 169,
          "mime_type": "image/jpeg",
          "source_url": "https://example.com/wp-content/uploads/2024/03/sunset-300x169.jpg"
        }
      },
      "image_meta": {
        "aperture": "0",
        "credit": "",
        "camera": "",
        "caption": "",
        "created_timestamp": "0",
        "copyright": "",
        "focal_length": "0",
        "iso": "0",
        "shutter_speed": "0",
        "title": "",
        "orientation": "0"
      }
    },
    "post": 123,
    "source_url": "https://example.com/wp-content/uploads/2024/03/sunset.jpg"
  }
]

By default, only media types supported by Web Stories are returned (images and videos). Audio files are excluded.

Get Media Item

Retrieves a single media item by ID.

GET /web-stories/v1/media/:id

curl https://yoursite.com/wp-json/web-stories/v1/media/456

Path Parameters

integer

required

Unique identifier for the media item

Response Fields

integer

Unique identifier for the attachment

date

string

Upload date in ISO 8601 format

slug

string

URL-friendly slug

title

object

Media title

author

integer

Uploader user ID

caption

object

Media caption

alt_text

string

Alternative text for accessibility

media_type

string

Type of media: image, video, file

mime_type

string

MIME type (e.g., image/jpeg, video/mp4)

media_details

object

Media file details

Show properties

width

integer

Width in pixels (defaults to 150 if not set)

height

integer

Height in pixels (defaults to 150 if not set)

file

string

Relative file path

filesize

integer

File size in bytes

sizes

object

Available image sizes (thumbnail, medium, large, etc.)

length

integer

Video duration in seconds (video only)

post

integer

Parent post ID (story this media is attached to)

source_url

string

Direct URL to the media file

original_id

integer

Original attachment ID if this is a copy

Upload Media

Uploads a new media file.

POST /web-stories/v1/media

curl -X POST https://yoursite.com/wp-json/web-stories/v1/media \
  -H "Content-Disposition: attachment; filename=image.jpg" \
  -u "username:password" \
  --data-binary @image.jpg

Headers

Content-Disposition

string

required

Must include filename: attachment; filename=image.jpg

Content-Type

string

MIME type of the file being uploaded

Request Body

Raw binary file data

Query Parameters

post

integer

Parent story ID to attach media to

original_id

integer

Original attachment ID to copy metadata from

Using Multipart Form Data

Alternatively, upload using multipart/form-data:

curl -X POST https://yoursite.com/wp-json/web-stories/v1/media \
  -u "username:password" \
  -F "[email protected]" \
  -F "title=My Image" \
  -F "alt_text=Description" \
  -F "post=123"

file

required

The file to upload

title

string

Media title

alt_text

string

Alternative text for images

caption

string

Media caption

post

integer

Parent story ID

original_id

integer

Original attachment ID to copy metadata from

Response

Returns the created media object with HTTP 201 status.

When post parameter is provided with a story ID, the media will be attached to that story. Web Stories allows attaching media to stories even though stories themselves are a custom post type.

When original_id is provided, metadata like title, caption, alt text, and base color will be copied from the original attachment.

Update Media

Updates media metadata (not the file itself).

PUT /web-stories/v1/media/:id

curl -X PUT https://yoursite.com/wp-json/web-stories/v1/media/456 \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "title": "Updated Title",
    "alt_text": "Updated description",
    "caption": "Updated caption"
  }'

Path Parameters

integer

required

Unique identifier for the media item

Request Body

title

string

Media title

alt_text

string

Alternative text

caption

string

Media caption

post

integer

Parent post ID

Response

Returns the updated media object with HTTP 200 status.

Delete Media

Deletes a media item.

DELETE /web-stories/v1/media/:id

curl -X DELETE https://yoursite.com/wp-json/web-stories/v1/media/456?force=true \
  -u "username:password"

Path Parameters

integer

required

Unique identifier for the media item

Query Parameters

force

boolean

default:"false"

Whether to bypass trash and force deletion

Response

{
  "deleted": true,
  "previous": {
    "id": 456,
    "title": {
      "rendered": "Deleted Media"
    }
  }
}

Supported Media Types

The Web Stories media endpoint supports the following media types:

Images

image/jpeg
image/png
image/gif (static and animated)
image/webp

Videos

video/mp4
video/webm

Note on Audio

While the endpoint inherits audio MIME types from WordPress, audio files are filtered out by default as they’re not currently supported in Web Stories.

Media Processing

When images are uploaded:

Dimension Defaults: If width/height cannot be determined, defaults to 150x150 pixels
Multiple Sizes: WordPress automatically generates multiple sizes (thumbnail, medium, large, etc.)
Base Color: The dominant color is extracted and stored in post meta
Optimization: Images may be processed based on WordPress media settings

Common Errors

rest_upload_invalid_mime_type

error

Status 400: The uploaded file type is not supportedEnsure you’re uploading a supported image or video format

rest_upload_file_too_big

error

Status 400: The uploaded file exceeds the maximum sizeCheck your WordPress and server upload limits

rest_cannot_edit

error

Status 403: You don’t have permission to edit this media itemRequired capability: edit_post for the attachment

rest_forbidden

error

Status 403: You don’t have permission to upload filesRequired capability: upload_files

Filtering Media Queries

The media endpoint applies custom filtering:

// Filter applied to WP_Query arguments
apply_filters('web_stories_rest_attachment_query', $args, $request);

// Filter applied to prepared response
apply_filters('web_stories_rest_prepare_attachment', $response, $post, $request);

You can use these filters in your theme or plugin to customize media query behavior.

REST API

JavaScript Packages

Hooks & Filters

Overview

List Media

Query Parameters

Response

Get Media Item

Path Parameters

Response Fields

Upload Media

Headers

Request Body

Query Parameters

Using Multipart Form Data

Response

Update Media

Path Parameters

Request Body

Response

Delete Media

Path Parameters

Query Parameters

Response

Supported Media Types

Images

Videos

Note on Audio

Media Processing

Common Errors

Filtering Media Queries

Build docs developers (and LLMs) love

REST API

JavaScript Packages

Hooks & Filters

​Overview

​List Media

​Query Parameters

​Response

​Get Media Item

​Path Parameters

​Response Fields

​Upload Media

​Headers

​Request Body

​Query Parameters

​Using Multipart Form Data

​Response

​Update Media

​Path Parameters

​Request Body

​Response

​Delete Media

​Path Parameters

​Query Parameters

​Response

​Supported Media Types

​Images

​Videos

​Note on Audio

​Media Processing

​Common Errors

​Filtering Media Queries

Build docs developers (and LLMs) love

Overview

List Media

Query Parameters

Response

Get Media Item

Path Parameters

Response Fields

Upload Media

Headers

Request Body

Query Parameters

Using Multipart Form Data

Response

Update Media

Path Parameters

Request Body

Response

Delete Media

Path Parameters

Query Parameters

Response

Supported Media Types

Images

Videos

Note on Audio

Media Processing

Common Errors

Filtering Media Queries