Resource Information
| Method | POST |
|---|---|
| URL | https://public-api.wordpress.com/rest/v1.1/sites/$site/posts/new |
| Requires authentication? | Yes |
Method Parameters
| Parameter | Type | Description |
|---|---|---|
| $site | (int|string) | Site ID or domain |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| context | (string) |
|
| http_envelope | (bool) |
|
| pretty | (bool) |
|
| meta | (string) | Optional. Loads data from the endpoints found in the 'meta' part of the response. Comma-separated list. Example: meta=site,likes |
| fields | (string) | Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title |
| callback | (string) | An optional JSONP callback function. |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| date | (iso 8601 datetime) | The post's creation time. |
| title | (html) | The post title. |
| content | (html) | The post content. |
| excerpt | (html) | An optional post excerpt. |
| slug | (string) | The name (slug) for the post, used in URLs. |
| author | (string) | The username or ID for the user to assign the post to. |
| publicize | (array|bool) | True or false if the post be shared to external services. An array of services if we only want to share to a select few. Defaults to true. |
| publicize_message | (string) | Custom message to be shared to external services. |
| status | (string) |
|
| sticky | (bool) |
|
| password | (string) | The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected. |
| parent | (int) | The post ID of the new post's parent. |
| type | (string) |
The post type. Defaults to 'post'. Post types besides post and page need to be whitelisted using the rest_api_allowed_post_types filter. |
| terms | (object) | Mapping of taxonomy to comma-separated list or array of terms (name or id) |
| categories | (array|string) | Comma-separated list or array of categories (name or id) |
| tags | (array|string) | Comma-separated list or array of tags (name or id) |
| format | (string) |
|
| featured_image | (string) | The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image. |
| media | (media) |
An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See allowed_file_types in the options response of the site endpoint. Errors produced by media uploads, if any, will be in `media_errors` in the response. Example: curl \ |
| media_urls | (array) | An array of URLs for images to attach to a post. Sideloads the media in for a post. Errors produced by media sideloading, if any, will be in `media_errors` in the response. |
| media_attrs | (array) |
An array of attributes (`title`, `description` and `caption`) are supported to assign to the media uploaded via the `media` or `media_urls` properties. You must use a numeric index for the keys of `media_attrs` which follow the same sequence as `media` and `media_urls`. Example: curl \ |
| metadata | (array) |
Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are avaiable for authenticated requests with proper capabilities. Protected meta keys can be made available with the rest_api_allowed_public_metadata filter. |
| discussion | (object) | A hash containing one or more of the following boolean values, which default to the blog's discussion preferences: `comments_open`, `pings_open` |
| likes_enabled | (bool) | Should the post be open to likes? Defaults to the blog's preference. |
| sharing_enabled | (bool) | Should sharing buttons show on this post? Defaults to true. |
| menu_order | (int) | (Pages Only) the order pages should appear in. Use 0 to maintain alphabetical order. |
| page_template | (string) | (Pages Only) The page template this page should use. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| ID | (int) | The post ID. |
| site_ID | (int) | The site ID. |
| author | (object) | The author of the post. |
| date | (iso 8601 datetime) | The post's creation time. |
| modified | (iso 8601 datetime) | The post's most recent update time. |
| title | (html) |
context dependent. |
| URL | (url) | The full permalink URL to the post. |
| short_URL | (url) | The wp.me short URL. |
| content | (html) |
context dependent. |
| excerpt | (html) |
context dependent. |
| slug | (string) | The name (slug) for the post, used in URLs. |
| guid | (string) | The GUID for the post. |
| status | (string) |
|
| sticky | (bool) | Is the post sticky? |
| password | (string) | The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected. |
| parent | (object|false) | A reference to the post's parent, if it has one. |
| type | (string) |
The post's post_type. Post types besides post, page and revision need to be whitelisted using the rest_api_allowed_post_types filter. |
| discussion | (object) | Hash of discussion options for the post |
| likes_enabled | (bool) | Is the post open to likes? |
| sharing_enabled | (bool) | Should sharing buttons show on this post? |
| like_count | (int) | The number of likes for this post. |
| i_like | (bool) | Does the current user like this post? |
| is_reblogged | (bool) | Did the current user reblog this post? |
| is_following | (bool) | Is the current user following this blog? |
| global_ID | (string) | A unique WordPress.com-wide representation of a post. |
| featured_image | (url) | The URL to the featured image for this post if it has one. |
| post_thumbnail | (object) | The attachment object for the featured image if it has one. |
| format | (string) |
|
| geo | (object|false) | |
| menu_order | (int) | (Pages Only) The order pages should appear in. |
| page_template | (string) | (Pages Only) The page template this page is using. |
| publicize_URLs | (array) | Array of Twitter and Facebook URLs published by this post. |
| terms | (object) | Hash of taxonomy names mapping to a hash of terms keyed by term name. |
| tags | (object) | Hash of tags (keyed by tag name) applied to the post. |
| categories | (object) | Hash of categories (keyed by category name) applied to the post. |
| attachments | (object) | Hash of post attachments (keyed by attachment ID). Returns the most recent 20 attachments. Use the `/sites/$site/media` endpoint to query the attachments beyond the default of 20 that are returned here. |
| attachment_count | (int) | The total number of attachments for this post. Use the `/sites/$site/media` endpoint to query the attachments beyond the default of 20 that are returned here. |
| metadata | (array) |
Array of post metadata keys and values. All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are available for authenticated requests with access. Protected meta keys can be made available with the rest_api_allowed_public_metadata filter. |
| meta | (object) | API result meta data |
| capabilities | (object) | List of post-specific permissions for the user; publish_post, edit_post, delete_post |
| revisions | (array) | List of post revision IDs. Only available for posts retrieved with context=edit. |
| other_URLs | (object) | List of URLs for this post. Permalink and slug suggestions. |
Resource Errors
These are the possible errors returned by this endpoint.
| HTTP Code | Error Identifier | Error Message |
|---|---|---|
| 403 | unauthorized | SEO tools are not enabled for this site. |
| 403 | invalid_input | Invalid file type. |
| 403 | unauthorized | User cannot delete post |
| 400 | invalid_field | Invalid API FIELD |
| 403 | unauthorized | User cannot access this private blog. |
| 403 | unauthorized | User cannot access this restricted blog |
| 403 | unauthorized | User cannot restore trashed posts |
| 403 | unauthorized | Assigned author cannot publish post. |
| 403 | unauthorized | User cannot delete posts |
| 403 | unauthorized | User cannot edit posts |
Example
curl \ -H 'authorization: Bearer YOUR_API_TOKEN' \ --data-urlencode 'title=Hello World' \ --data-urlencode 'content=Hello. I am a test post. I was created by the API' \ --data-urlencode 'tags=tests' \ --data-urlencode 'categories=API' \ 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/new/'
<?php
$options = array (
'http' =>
array (
'ignore_errors' => true,
'method' => 'POST',
'header' =>
array (
0 => 'authorization: Bearer YOUR_API_TOKEN',
1 => 'Content-Type: application/x-www-form-urlencoded',
),
'content' =>
http_build_query( array (
'title' => 'Hello World',
'content' => 'Hello. I am a test post. I was created by the API',
'tags' => 'tests',
'categories' => 'API',
)),
),
);
$context = stream_context_create( $options );
$response = file_get_contents(
'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/new/',
false,
$context
);
$response = json_decode( $response );
?>
Response
{
"ID": 11898,
"site_ID": "82974409",
"author": {
"ID": 78972699,
"login": "apiexamples",
"email": false,
"name": "apiexamples",
"first_name": "",
"last_name": "",
"nice_name": "apiexamples",
"URL": "http:\/\/apiexamples.wordpress.com",
"avatar_URL": "https:\/\/1.gravatar.com\/avatar\/a2afb7b6c0e23e5d363d8612fb1bd5ad?s=96&d=identicon&r=G",
"profile_URL": "http:\/\/en.gravatar.com\/apiexamples",
"site_ID": 82974409
},
"date": "2016-11-17T06:01:17+00:00",
"modified": "2016-11-17T06:01:17+00:00",
"title": "Hello World",
"URL": "https:\/\/apiexamples.wordpress.com\/2016\/11\/17\/hello-world-3\/",
"short_URL": "http:\/\/wp.me\/p5C9qV-35U",
"content": "<p>Hello. I am a test post. I was created by the API<\/p>\n",
"excerpt": "<p>Hello. I am a test post. I was created by the API<\/p>\n",
"slug": "hello-world-3",
"guid": "https:\/\/apiexamples.wordpress.com\/2016\/11\/17\/hello-world-3\/",
"status": "publish",
"sticky": false,
"password": "",
"parent": false,
"type": "post",
"discussion": {
"comments_open": true,
"comment_status": "open",
"pings_open": true,
"ping_status": "open",
"comment_count": 0
},
"likes_enabled": true,
"sharing_enabled": true,
"like_count": 0,
"i_like": false,
"is_reblogged": false,
"is_following": true,
"global_ID": "da1bd9d88605554c45ccd49a0448130f",
"featured_image": "",
"post_thumbnail": null,
"format": "standard",
"geo": false,
"menu_order": 0,
"page_template": "",
"publicize_URLs": [],
"terms": {
"category": {
"API": {
"ID": 4276,
"name": "API",
"slug": "api",
"description": "",
"post_count": 4,
"parent": 0,
"meta": {
"links": {
"self": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/categories\/slug:api",
"help": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/categories\/slug:api\/help",
"site": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409"
}
}
}
},
"post_tag": {
"tests": {
"ID": 2436,
"name": "tests",
"slug": "tests",
"description": "",
"post_count": 4,
"meta": {
"links": {
"self": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/tags\/slug:tests",
"help": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/tags\/slug:tests\/help",
"site": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409"
}
}
}
},
"post_format": {},
"mentions": {}
},
"tags": {
"tests": {
"ID": 2436,
"name": "tests",
"slug": "tests",
"description": "",
"post_count": 4,
"meta": {
"links": {
"self": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/tags\/slug:tests",
"help": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/tags\/slug:tests\/help",
"site": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409"
}
}
}
},
"categories": {
"API": {
"ID": 4276,
"name": "API",
"slug": "api",
"description": "",
"post_count": 4,
"parent": 0,
"meta": {
"links": {
"self": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/categories\/slug:api",
"help": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/categories\/slug:api\/help",
"site": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409"
}
}
}
},
"attachments": {},
"attachment_count": 0,
"metadata": [
{
"id": "53332",
"key": "jabber_published",
"value": "1479362479"
}
],
"meta": {
"links": {
"self": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/posts\/11898",
"help": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/posts\/11898\/help",
"site": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409",
"replies": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/posts\/11898\/replies\/",
"likes": "https:\/\/public-api.wordpress.com\/rest\/v1.1\/sites\/82974409\/posts\/11898\/likes\/"
}
},
"capabilities": {
"publish_post": true,
"delete_post": true,
"edit_post": true
},
"other_URLs": {
"suggested_slug": "hello-world-3",
"permalink_URL": "https:\/\/apiexamples.wordpress.com\/2016\/11\/17\/%postname%\/"
}
}
Developer Resources 