# Media

<div class="section route">

<div class="primary">

## Schema

The schema defines all the fields that exist within a Media Item record. Any response from these endpoints can be expected to contain the fields below unless the \`\_filter\` query parameter is used or the schema field only appears in a specific context.

<table class="attributes">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr id="schema-date">
<td><code>date</code></td>
<td>The date the post was published, in the site’s timezone.
<p>JSON data type: string or null,<br />
Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-date_gmt">
<td><code>date_gmt</code></td>
<td>The date the post was published, as GMT.
<p>JSON data type: string or null,<br />
Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-guid">
<td><code>guid</code></td>
<td>The globally unique identifier for the post.
<p>JSON data type: object</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-id">
<td><code>id</code></td>
<td>Unique identifier for the post.
<p>JSON data type: integer</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-link">
<td><code>link</code></td>
<td>URL to the post.
<p>JSON data type: string,<br />
Format: uri</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-modified">
<td><code>modified</code></td>
<td>The date the post was last modified, in the site’s timezone.
<p>JSON data type: string,<br />
Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-modified_gmt">
<td><code>modified_gmt</code></td>
<td>The date the post was last modified, as GMT.
<p>JSON data type: string,<br />
Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-slug">
<td><code>slug</code></td>
<td>An alphanumeric identifier for the post unique to its type.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-status">
<td><code>status</code></td>
<td>A named status for the post.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code></p>
<p>One of: <code>publish</code>, <code>future</code>, <code>draft</code>, <code>pending</code>, <code>private</code></p></td>
</tr>
<tr id="schema-type">
<td><code>type</code></td>
<td>Type of post.
<p>JSON data type: string</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-permalink_template">
<td><code>permalink_template</code></td>
<td>Permalink template for the post.
<p>JSON data type: string</p>
<p>Read only</p>
<p>Context: <code>edit</code></p></td>
</tr>
<tr id="schema-generated_slug">
<td><code>generated_slug</code></td>
<td>Slug automatically generated from the post title.
<p>JSON data type: string</p>
<p>Read only</p>
<p>Context: <code>edit</code></p></td>
</tr>
<tr id="schema-title">
<td><code>title</code></td>
<td>The title for the post.
<p>JSON data type: object</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-author">
<td><code>author</code></td>
<td>The ID for the author of the post.
<p>JSON data type: integer</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-comment_status">
<td><code>comment_status</code></td>
<td>Whether or not comments are open on the post.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code></p>
<p>One of: <code>open</code>, <code>closed</code></p></td>
</tr>
<tr id="schema-ping_status">
<td><code>ping_status</code></td>
<td>Whether or not the post can be pinged.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code></p>
<p>One of: <code>open</code>, <code>closed</code></p></td>
</tr>
<tr id="schema-meta">
<td><code>meta</code></td>
<td>Meta fields.
<p>JSON data type: object</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-template">
<td><code>template</code></td>
<td>The theme file to use to display the post.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-alt_text">
<td><code>alt_text</code></td>
<td>Alternative text to display when attachment is not displayed.
<p>JSON data type: string</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-caption">
<td><code>caption</code></td>
<td>The attachment caption.
<p>JSON data type: object</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-description">
<td><code>description</code></td>
<td>The attachment description.
<p>JSON data type: object</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-media_type">
<td><code>media_type</code></td>
<td>Attachment type.
<p>JSON data type: string</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
<p>One of: <code>image</code>, <code>file</code></p></td>
</tr>
<tr id="schema-mime_type">
<td><code>mime_type</code></td>
<td>The attachment MIME type.
<p>JSON data type: string</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-media_details">
<td><code>media_details</code></td>
<td>Details about the media file, specific to its type.
<p>JSON data type: object</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-post">
<td><code>post</code></td>
<td>The ID for the associated post of the attachment.
<p>JSON data type: integer</p>
<p>Context: <code>view</code>, <code>edit</code></p></td>
</tr>
<tr id="schema-source_url">
<td><code>source_url</code></td>
<td>URL to the original attachment file.
<p>JSON data type: string,<br />
Format: uri</p>
<p>Read only</p>
<p>Context: <code>view</code>, <code>edit</code>, <code>embed</code></p></td>
</tr>
<tr id="schema-missing_image_sizes">
<td><code>missing_image_sizes</code></td>
<td>List of the missing image sizes of the attachment.
<p>JSON data type: array</p>
<p>Read only</p>
<p>Context: <code>edit</code></p></td>
</tr>
</tbody>
</table>

</div>

</div>

<div>

<div class="section route">

<div class="primary">

## List Media

Query this endpoint to retrieve a collection of media. The response you receive can be controlled and filtered using the URL query parameters below.

### Definition

`GET /wp/v2/media`

### Example Request

`$ curl https://example.com/wp-json/wp/v2/media`

</div>

<div class="secondary">

### Arguments

<table class="arguments">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr>
<td><code>context</code></td>
<td>Scope under which the request is made; determines fields present in response.
<p>Default: <code>view</code></p>
<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p></td>
</tr>
<tr>
<td><code>page</code></td>
<td>Current page of the collection.
<p>Default: <code>1</code></p></td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Maximum number of items to be returned in result set.
<p>Default: <code>10</code></p></td>
</tr>
<tr>
<td><code>search</code></td>
<td>Limit results to those matching a string.</td>
</tr>
<tr>
<td><code>after</code></td>
<td>Limit response to posts published after a given ISO8601 compliant date.</td>
</tr>
<tr>
<td><code>modified_after</code></td>
<td>Limit response to posts modified after a given ISO8601 compliant date.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>Limit result set to posts assigned to specific authors.</td>
</tr>
<tr>
<td><code>author_exclude</code></td>
<td>Ensure result set excludes posts assigned to specific authors.</td>
</tr>
<tr>
<td><code>before</code></td>
<td>Limit response to posts published before a given ISO8601 compliant date.</td>
</tr>
<tr>
<td><code>modified_before</code></td>
<td>Limit response to posts modified before a given ISO8601 compliant date.</td>
</tr>
<tr>
<td><code>exclude</code></td>
<td>Ensure result set excludes specific IDs.</td>
</tr>
<tr>
<td><code>include</code></td>
<td>Limit result set to specific IDs.</td>
</tr>
<tr>
<td><code>offset</code></td>
<td>Offset the result set by a specific number of items.</td>
</tr>
<tr>
<td><code>order</code></td>
<td>Order sort attribute ascending or descending.
<p>Default: <code>desc</code></p>
<p>One of: <code>asc</code>, <code>desc</code></p></td>
</tr>
<tr>
<td><code>orderby</code></td>
<td>Sort collection by post attribute.
<p>Default: <code>date</code></p>
<p>One of: <code>author</code>, <code>date</code>, <code>id</code>, <code>include</code>, <code>modified</code>, <code>parent</code>, <code>relevance</code>, <code>slug</code>, <code>include_slugs</code>, <code>title</code></p></td>
</tr>
<tr>
<td><code>parent</code></td>
<td>Limit result set to items with particular parent IDs.</td>
</tr>
<tr>
<td><code>parent_exclude</code></td>
<td>Limit result set to all items except those of a particular parent ID.</td>
</tr>
<tr>
<td><code>search_columns</code></td>
<td>Array of column names to be searched.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>Limit result set to posts with one or more specific slugs.</td>
</tr>
<tr>
<td><code>status</code></td>
<td>Limit result set to posts assigned one or more statuses.
<p>Default: <code>inherit</code></p></td>
</tr>
<tr>
<td><code>media_type</code></td>
<td>Limit result set to attachments of a particular media type.<br />
One of: <code>image</code>, <code>video</code>, <code>text</code>, <code>application</code>, <code>audio</code></td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>Limit result set to attachments of a particular MIME type.</td>
</tr>
</tbody>
</table>

</div>

</div>

<div class="section route">

<div class="primary">

## Create a Media Item

### Arguments

<table class="arguments">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr>
<td><a href="#schema-date"><code>date</code></a></td>
<td>The date the post was published, in the site’s timezone.</td>
</tr>
<tr>
<td><a href="#schema-date_gmt"><code>date_gmt</code></a></td>
<td>The date the post was published, as GMT.</td>
</tr>
<tr>
<td><a href="#schema-slug"><code>slug</code></a></td>
<td>An alphanumeric identifier for the post unique to its type.</td>
</tr>
<tr>
<td><a href="#schema-status"><code>status</code></a></td>
<td>A named status for the post.<br />
One of: <code>publish</code>, <code>future</code>, <code>draft</code>, <code>pending</code>, <code>private</code></td>
</tr>
<tr>
<td><a href="#schema-title"><code>title</code></a></td>
<td>The title for the post.</td>
</tr>
<tr>
<td><a href="#schema-author"><code>author</code></a></td>
<td>The ID for the author of the post.</td>
</tr>
<tr>
<td><a href="#schema-comment_status"><code>comment_status</code></a></td>
<td>Whether or not comments are open on the post.<br />
One of: <code>open</code>, <code>closed</code></td>
</tr>
<tr>
<td><a href="#schema-ping_status"><code>ping_status</code></a></td>
<td>Whether or not the post can be pinged.<br />
One of: <code>open</code>, <code>closed</code></td>
</tr>
<tr>
<td><a href="#schema-meta"><code>meta</code></a></td>
<td>Meta fields.</td>
</tr>
<tr>
<td><a href="#schema-template"><code>template</code></a></td>
<td>The theme file to use to display the post.</td>
</tr>
<tr>
<td><a href="#schema-alt_text"><code>alt_text</code></a></td>
<td>Alternative text to display when attachment is not displayed.</td>
</tr>
<tr>
<td><a href="#schema-caption"><code>caption</code></a></td>
<td>The attachment caption.</td>
</tr>
<tr>
<td><a href="#schema-description"><code>description</code></a></td>
<td>The attachment description.</td>
</tr>
<tr>
<td><a href="#schema-post"><code>post</code></a></td>
<td>The ID for the associated post of the attachment.</td>
</tr>
</tbody>
</table>

</div>

<div class="secondary">

### Definition

`POST /wp/v2/media`

</div>

</div>

<div class="section route">

<div class="primary">

## Retrieve a Media Item

### Definition & Example Request

`GET /wp/v2/media/<id>`

Query this endpoint to retrieve a specific Media Item record.

`$ curl https://example.com/wp-json/wp/v2/media/<id>`

</div>

<div class="secondary">

### Arguments

<table class="arguments">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr>
<td><code>id</code></td>
<td>Unique identifier for the post.</td>
</tr>
<tr>
<td><code>context</code></td>
<td>Scope under which the request is made; determines fields present in response.
<p>Default: <code>view</code></p>
<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p></td>
</tr>
</tbody>
</table>

</div>

</div>

<div class="section route">

<div class="primary">

## Update a Media Item

### Arguments

<table class="arguments">
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<tbody>
<tr>
<td><a href="#schema-id"><code>id</code></a></td>
<td>Unique identifier for the post.</td>
</tr>
<tr>
<td><a href="#schema-date"><code>date</code></a></td>
<td>The date the post was published, in the site’s timezone.</td>
</tr>
<tr>
<td><a href="#schema-date_gmt"><code>date_gmt</code></a></td>
<td>The date the post was published, as GMT.</td>
</tr>
<tr>
<td><a href="#schema-slug"><code>slug</code></a></td>
<td>An alphanumeric identifier for the post unique to its type.</td>
</tr>
<tr>
<td><a href="#schema-status"><code>status</code></a></td>
<td>A named status for the post.<br />
One of: <code>publish</code>, <code>future</code>, <code>draft</code>, <code>pending</code>, <code>private</code></td>
</tr>
<tr>
<td><a href="#schema-title"><code>title</code></a></td>
<td>The title for the post.</td>
</tr>
<tr>
<td><a href="#schema-author"><code>author</code></a></td>
<td>The ID for the author of the post.</td>
</tr>
<tr>
<td><a href="#schema-comment_status"><code>comment_status</code></a></td>
<td>Whether or not comments are open on the post.<br />
One of: <code>open</code>, <code>closed</code></td>
</tr>
<tr>
<td><a href="#schema-ping_status"><code>ping_status</code></a></td>
<td>Whether or not the post can be pinged.<br />
One of: <code>open</code>, <code>closed</code></td>
</tr>
<tr>
<td><a href="#schema-meta"><code>meta</code></a></td>
<td>Meta fields.</td>
</tr>
<tr>
<td><a href="#schema-template"><code>template</code></a></td>
<td>The theme file to use to display the post.</td>
</tr>
<tr>
<td><a href="#schema-alt_text"><code>alt_text</code></a></td>
<td>Alternative text to display when attachment is not displayed.</td>
</tr>
<tr>
<td><a href="#schema-caption"><code>caption</code></a></td>
<td>The attachment caption.</td>
</tr>
<tr>
<td><a href="#schema-description"><code>description</code></a></td>
<td>The attachment description.</td>
</tr>
<tr>
<td><a href="#schema-post"><code>post</code></a></td>
<td>The ID for the associated post of the attachment.</td>
</tr>
</tbody>
</table>

</div>

<div class="secondary">

### Definition

`POST /wp/v2/media/<id>`

### Example Request

</div>

</div>

<div class="section route">

<div class="primary">

## Delete a Media Item

### Arguments

|         |                                             |
|---------|---------------------------------------------|
| `id`    | Unique identifier for the post.             |
| `force` | Whether to bypass Trash and force deletion. |

</div>

<div class="secondary">

### Definition

`DELETE /wp/v2/media/<id>`

### Example Request

`$ curl -X DELETE https://example.com/wp-json/wp/v2/media/<id>`

</div>

</div>

</div>