Categories

These routes allow you to retrieve/create/update/delete categories.

Possible routes (endpoints are described below):

/wp/v2/categories       // works with all categories
/wp/v2/categories/{ID}  // works with the specified category instead of {ID}

Controller class: WP_REST_Terms_Controller{}

Contents:

Resource schema
wp/v2/categories
List of categories
Creating a category
wp/v2/categories/{id}
Getting a category
Updating a category
Deleting a category

Resource schema

The schema shows all fields that exist for the object: the fields of the object that the request will return.

Parameter	Context	Description
id number	`view, edit, embed`	Term ID (category). Read-only.
count number	`view, edit`	Number of posts in the term (category). Read-only.
description string	`view, edit`	Description of the term (category).
link string, uri	`view, edit, embed`	URL of the term (category). Read-only.
name string	`view, edit, embed`	Name of the term (category).
slug string	`view, edit, embed`	Slug of the term (category), usually created from the name.
taxonomy string	`view, edit, embed` \| Name of the taxonomy. Read-only. Can be: `category`, `post_tag`, `nav_menu`, `link_category`, `post_format`
parent number	`view, edit`	ID of the parent term.
meta object	`view, edit`	Meta fields.

Context — shows which fields of the object will be returned in the response when creating a request in the specified context. For example, when updating or creating a category, the fields corresponding to the edit context will be returned.

wp/v2/categories

An OPTIONS request to the route will return a complete description of this route: endpoints, their parameters, schema.

$ curl -X OPTIONS -i http://demo.wp-api.org/wp-json/wp/v2/categories

List of categories

Retrieves a list of categories, similar to get_categories().

Request type

GET /wp/v2/categories

Request parameters

context: The area in which the request is made; defines the fields present in the response.
Can be: view, embed, edit
Default: view
page: The current pagination page.
Default: 1
per_page: The maximum number of items returned in the result.
Default: 10
search: Limit results to those that match the string.
exclude: Excludes categories by ID.
include: Shows only the specified categories. ID is specified.
orderby: Which field to sort by?
Can be: id, include, name, slug, term_group, description, count
Default: name
order: How to sort?
Can be: asc, desc
Default: asc
hide_empty: Hide empty categories (where there are no posts)?
parent: ID of the parent category whose children need to be retrieved.
post: ID of the post whose categories need to be retrieved.
slug: Specify the slugs of the categories to be retrieved.

Example request

http://demo.wp-api.org/wp-json/wp/v2/categories

Get categories of post 1

http://demo.wp-api.org/wp-json/wp/v2/categories?post=1

Creating a category

The algorithm is similar to the operation of the function wp_insert_category().

Request type

Access: authorization required

POST /wp/v2/categories

Request parameters

name(required): Name of the term (category).
description: Description of the term (category).
slug: Slug of the term (category), usually created from the name.
parent: ID of the parent term.
meta: Meta fields.

Example request:

POST http://example.com/wp-json/wp/v2/categories?name=My category

Response

{
	"id": 6,
	"count": 0,
	"description": "",
	"link": "http://example.com/cat/my-category/",
	"name": "My category",
	"slug": "my-category",
	"taxonomy": "category",
	"parent": 0,
	"meta": [],
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories/6"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
			}
		],
		"wp:post_type": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts?categories=6"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	}
}

wp/v2/categories/{id}

An OPTIONS request to the route will return a complete description of this route: endpoints, their parameters, schema.

$ curl -X OPTIONS -i http://demo.wp-api.org/wp-json/wp/v2/categories/1

Getting a category

The algorithm is similar to the operation of the function get_category().

Request type

GET /wp/v2/categories/{id}

Request parameters

id(number): Identifier of the term.
context(string): The area in which the request is made; defines the fields present in the response.
Can be: view, embed, edit
Default: view

Example request

http://demo.wp-api.org/wp-json/wp/v2/categories/25

Updating a category

The algorithm is similar to the operation of the function wp_update_category().

Request type

POST /wp/v2/categories/{id}

Request parameters

id(required): ID of the term (category).
name: Name of the term (category).
description: Description of the term (category).
slug: Slug of the term (category), usually created from the name.
parent: ID of the parent term.
meta: Meta fields.

Example request

$ curl -X POST http://demo.wp-api.org/wp-json/wp/v2/categories/25 -d '{"name":"New name"}'

POST http://example.com/wp-json/wp/v2/categories/6?name=My category&slug=My category

Response

{
	"id": 6,
	"count": 0,
	"description": "",
	"link": "http://example.com/cat/my-category/",
	"name": "My category",
	"slug": "my-category",
	"taxonomy": "category",
	"parent": 0,
	"meta": [],
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories/6"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
			}
		],
		"wp:post_type": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts?categories=6"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	}
}

Deleting a category

The algorithm is similar to the operation of the function wp_delete_term().

Request type

DELETE /wp/v2/categories/{id}

Request parameters

id(required): ID of the term (category).
force: Must always be true, as terms do not support trash.

Example request

$ curl -X DELETE http://example.com/wp-json/wp/v2/categories/6?force=true

Response

{
	"deleted": true,
	"previous": {
		"id": 6,
		"count": 0,
		"description": "",
		"link": "http://example.com/cat/my-category/",
		"name": "My category",
		"slug": "my-category",
		"taxonomy": "category",
		"parent": 0,
		"meta": []
	}
}

Response if such a category does not exist

{
	"code": "rest_term_invalid",
	"message": "The item does not exist.",
	"data": {
		"status": 404
	}
}