Difference between revisions of "XML-RPC WordPress API/Posts"

Latest revision as of 13:42, 28 July 2020

wp.getPost

Retrieve a post of any registered post type.

Added in WordPress 3.4.

Parameters

string username
string password
int post_id
array fields: Optional. List of field or meta-field names to include in response.

Return Values

struct: Note that the exact fields returned depends on the fields parameter.
- string post_id
- string post_title¹
- datetime post_date¹
- datetime post_date_gmt¹
- datetime post_modified¹
- datetime post_modified_gmt¹
- string post_status¹
- string post_type¹
- string post_format¹
- string post_name¹
- string post_author¹ author id
- string post_password¹
- string post_excerpt¹
- string post_content¹
- string post_parent¹
- string post_mime_type¹
- string link¹
- string guid¹
- int menu_order¹
- string comment_status¹
- string ping_status¹
- bool sticky¹
- struct post_thumbnail¹: See wp.getMediaItem.
- array terms
  - struct: See wp.getTerm
- array custom_fields
  - struct
    - string id
    - string key
    - string value
- struct enclosure
  - string url
  - int length
  - string type

¹ post meta-field

Notes

In the older metaweblog API, the "Introduction" and the "Read More" content for a post were returned in separate fields "description" and "mt_text_more". In the WordPress API, the two values are combined in the single "post_content" field, separated by the  tag.

Errors

401
- If user does not have permission to edit the post.
404
- If no post with that post_id exists.

Filters

xmlrpc_default_post_fields

The default set of fields to be returned can be controlled using the xmlrpc_default_post_fields filter. The default value for this filter is:

array( 'post', 'terms', 'custom_fields' )

xmlrpc_prepare_post

Immediately before returning the prepared post data, the value is passed through the xmlrpc_prepare_post filter. The filter has three parameters:

The prepared post data about to be returned
The original post data array, see get_post.
The fields parameter value.

wp.getPosts

Retrieve list of posts of any registered post type.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
struct filter: Optional.
- string post_type
- string post_status
- int number
- int offset
- string orderby
- string s
- string order
array fields: Optional. See #wp.getPost.

Return Values

array
- struct: See #wp.getPost.

Notes

Response will only contain posts that the user has permission to edit. Therefore, there may be fewer than filter['number'] posts in the response.

Filters

Supports same filters as #wp.getPost.

wp.newPost

Create a new post of any registered post type.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
struct content
- string post_type
- string post_status
- string post_title
- int post_author
- string post_excerpt
- string post_content
- datetime post_date_gmt | post_date
- string post_format
- string post_name: Encoded URL (slug)
- string post_password
- string comment_status
- string ping_status
- int sticky
- int post_thumbnail
- int post_parent
- array custom_fields
  - struct
    - string key
    - string value
- struct terms: Taxonomy names as keys, array of term IDs as values.
- struct terms_names: Taxonomy names as keys, array of term names as values.
- struct enclosure
  - string url
  - int length
  - string type
- any other fields supported by wp_insert_post

Return Values

string post_id

Errors

401
- If the user does not have the edit_posts cap for this post type.
- If user does not have permission to create post of the specified post_status.
- If post_author is different than the user's ID and the user does not have the edit_others_posts cap for this post type.
- If sticky is passed and user does not have permission to make the post sticky, regardless if sticky is set to 0, 1, false or true.
- If a taxonomy in terms or terms_names is not supported by this post type.
- If terms or terms_names is set but user does not have assign_terms cap.
- If an ambiguous term name is used in terms_names.
403
- If invalid post_type is specified.
- If an invalid term ID is specified in terms.
404
- If no author with that post_author ID exists.
- If no attachment with that post_thumbnail ID exists.

wp.editPost

Edit an existing post of any registered post type.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
int post_id
struct content: See #wp.newPost for valid set of fields. Only needs to contain fields that you wish to modify; all other fields will retain their current values.

Notes

You must pass the meta ID to update any existing items in the custom_fields array.

Return Values

bool true

Errors

404
- If no post with that post_id exists.

Can also return same errors as #wp.newPost.

wp.deletePost

Delete an existing post of any registered post type.

See wp_delete_post for exact behavior based on post type.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
int post_id

Return Values

bool true

Errors

401
- If the user does not have permission to delete the post.
404
- If no post with that post_id exists.

wp.getPostType

Retrieve a registered post type.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
string post_type_name
array fields: Optional. List of field or meta-field names to include in response.

Return Values

struct: Note that the exact fields returned depends on the fields parameter.
- string name
- string label
- bool hierarchical
- bool public
- bool show_ui
- bool _builtin
- bool has_archive
- struct supports: Features supported by the theme as keys, values always true. See post_type_supports.
- struct labels¹
- struct cap²
- bool map_meta_cap²
- int menu_position³
- string menu_icon³
- bool show_in_menu³
- array taxonomies⁴

¹ labels meta-field
² capabilities meta-field.
³ menu meta-field.
⁴ taxonomies meta-field.

Errors

401
- If the user does not have the edit_posts cap for this post type.
403
- If invalid post type name is specified.

Filters

The default set of fields to be returned can be controlled using the xmlrpc_default_posttype_fields filter. The default value for this filter is:

array( 'labels', 'capabilities', 'taxonomies' )

wp.getPostTypes

Retrieve list of registered post types.

Added in WordPress 3.4.

Parameters

int blog_id
string username
string password
struct filter: Optional. See get_post_types for filter options.
array fields: Optional. See #wp.getPostType.

Return Values

struct: Post type names as keys, post types as values. See #wp.getPostType.

Notes

Response will only contain post types for which the user has the edit_posts cap.

Filters

The default set of fields to be returned can be controlled using the xmlrpc_default_posttype_fields filter. The default value for this filter is:

array( 'labels', 'capabilities', 'taxonomies' )

wp.getPostFormats

Retrieve list of post formats.

Added in WordPress 3.1.

Parameters

int blog_id
string username
string password
array filter: Optional.
- bool show-supported: Retrieve both the complete list of post formats, and the specific list of formats supported by the current theme.

Return Values

If filter or show-supported is omitted or false:

struct: keys are the formats, values are the display name for the format.

Example response data:

array(
  'standard' => 'Standard',
  'aside'    => 'Aside',
  'image'    => 'Image',
  ...
);

If show-supported is set:

struct
- struct all: All post formats, in key/value format as described above.
- array (of strings) supported: List of post formats supported by the current theme.

Example response data:

array(
  'all' => array(
    'standard' => 'Standard',
    'aside'    => 'Aside',
    'image'    => 'Image',
    ...
  ),
  'supported' => array( 'standard', 'image' )
);

Errors

403
- If the user does not have the edit_posts cap.

wp.getPostStatusList

Retrieve list of supported values for post_status field on posts.

Added in WordPress 2.5.

Parameters

int blog_id
string username
string password

Return Values

struct: keys are the statuses, values are the display name for the status.

Example response data:

array(
  'draft'   => 'Draft',
  'pending' => 'Pending Review',
  'private' => 'Private',
  'publish' => 'Published'
);

Errors

403
- If the user does not have the edit_posts cap.

@@ Line 7: / Line 7: @@
 === Parameters ===
-* int <tt>blog_id</tt>
 * string <tt>username</tt>
 * string <tt>password</tt>
@@ Line 16: / Line 15: @@
 * struct: Note that the exact fields returned depends on the <tt>fields</tt> parameter.
-** string <tt>post_id</tt>
+** string <tt> post_id </tt>
 ** string <tt>post_title</tt><sup>1</sup>
 ** datetime <tt>post_date</tt><sup>1</sup>
@@ Line 52: / Line 51: @@
 <sup>1</sup> <tt>post</tt> meta-field<br>
+==== Notes ====
+* In the older metaweblog API, the "Introduction" and the "Read More" content for a post were returned in separate fields "description" and "mt_text_more". In the WordPress API, the two values are combined in the single "post_content" field, separated by the &lt;!--more--> tag.
 === Errors ===
@@ Line 93: / Line 96: @@
 ** int <tt>offset</tt>
 ** string <tt>orderby</tt>
+** string <tt>s</tt>
 ** string <tt>order</tt>
 * array <tt>fields</tt>: Optional. See [[#wp.getPost]].
@@ Line 129: / Line 133: @@
 ** datetime <tt>post_date_gmt</tt> | <tt>post_date</tt>
 ** string <tt>post_format</tt>
-** string <tt>post_name</tt>
+** string <tt>post_name</tt>: Encoded URL (slug)
 ** string <tt>post_password</tt>
 ** string <tt>comment_status</tt>
 ** string <tt>ping_status</tt>
-** bool <tt>sticky</tt>
+** int <tt>sticky</tt>
 ** int <tt>post_thumbnail</tt>
 ** int <tt>post_parent</tt>
@@ Line 158: / Line 162: @@
 ** If user does not have permission to create post of the specified <tt>post_status</tt>.
 ** If <tt>post_author</tt> is different than the user's ID and the user does not have the <tt>[[Roles_and_Capabilities#edit_others_posts|edit_others_posts]]</tt> cap for this post type.
-** If <tt>sticky=true</tt> and user does not have permission to make the post sticky.
+** If <tt>sticky</tt> is passed and user does not have permission to make the post sticky, regardless if <tt>sticky</tt> is set to <tt>0</tt>, <tt>1</tt>, <tt>false</tt> or <tt>true</tt>.
 ** If a taxonomy in <tt>terms</tt> or <tt>terms_names</tt> is not supported by this post type.
 ** If <tt>terms</tt> or <tt>terms_names</tt> is set but user does not have <tt>[[Roles_and_Capabilities#assign_terms|assign_terms]]</tt> cap.
@@ Line 181: / Line 185: @@
 * string <tt>password</tt>
 * int <tt>post_id</tt>
 * struct <tt>content</tt>: See [[#wp.newPost]] for valid set of fields. Only needs to contain fields that you wish to modify; all other fields will retain their current values.
+=== Notes ===
+* You must pass the meta ID to update any existing items in the custom_fields array.
 === Return Values ===
@@ Line 311: / Line 319: @@
 * string <tt>password</tt>
 * array <tt>filter</tt>: Optional.
-** bool <tt>show-supported</tt>: Only retrieve post formats supported by the current theme.
+** bool <tt>show-supported</tt>: Retrieve both the complete list of post formats, and the specific list of formats supported by the current theme.
 === Return Values ===

Codex