WordPress Categories API

openapi: 3.0.3
info:
  title: WordPress REST Block Types Categories API
  description: The WordPress REST API provides endpoints for WordPress data types that allow developers to interact with sites remotely by sending and receiving JSON objects. It is the backbone of the WordPress Block Editor and enables headless CMS, mobile apps, and third-party integrations.
  version: v2
  contact:
    name: WordPress Developer Resources
    url: https://developer.wordpress.org/rest-api/
  license:
    name: GPL-2.0-or-later
    url: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  x-generated-from: documentation
servers:
- url: https://{site}/wp-json
  description: WordPress site REST API root
  variables:
    site:
      default: example.com
      description: Your WordPress site hostname
security:
- cookieAuth: []
- basicAuth: []
- applicationPassword: []
tags:
- name: Categories
  description: Manage post categories
paths:
  /wp/v2/categories:
    get:
      operationId: listCategories
      summary: WordPress List Categories
      description: Retrieves a collection of post categories.
      tags:
      - Categories
      parameters:
      - name: page
        in: query
        description: Current page of the collection.
        schema:
          type: integer
          default: 1
        example: 1
      - name: per_page
        in: query
        description: Maximum number of items.
        schema:
          type: integer
          default: 10
        example: 10
      - name: search
        in: query
        description: Limit results to matching categories.
        schema:
          type: string
        example: technology
      - name: hide_empty
        in: query
        description: Whether to hide terms not assigned to any posts.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: A list of categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Term'
              examples:
                ListCategories200Example:
                  summary: Default listCategories 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    count: 12
                    description: ''
                    link: https://example.com/category/uncategorized/
                    name: Uncategorized
                    slug: uncategorized
                    taxonomy: category
                    parent: 0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCategory
      summary: WordPress Create Category
      description: Creates a new category. Requires authentication.
      tags:
      - Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TermInput'
      responses:
        '201':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Term'
              examples:
                CreateCategory201Example:
                  summary: Default createCategory 201 response
                  x-microcks-default: true
                  value:
                    id: 5
                    name: Technology
                    slug: technology
                    taxonomy: category
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Unauthorized401Example:
              summary: Unauthorized example
              x-microcks-default: true
              value:
                code: rest_not_logged_in
                message: You are not currently logged in.
                data:
                  status: 401
  schemas:
    Term:
      type: object
      description: A WordPress taxonomy term (category or tag)
      properties:
        id:
          type: integer
          description: Unique identifier for the term
          example: 1
        count:
          type: integer
          description: Number of published posts for the term
          example: 12
        description:
          type: string
          description: HTML description of the term
          example: ''
        link:
          type: string
          description: URL of the term
          example: https://example.com/category/uncategorized/
        name:
          type: string
          description: HTML title for the term
          example: Uncategorized
        slug:
          type: string
          description: An alphanumeric identifier for the term
          example: uncategorized
        taxonomy:
          type: string
          description: Type attribution for the term
          example: category
        parent:
          type: integer
          description: The parent term ID
          example: 0
    ErrorResponse:
      type: object
      description: A WordPress REST API error response
      properties:
        code:
          type: string
          description: Error code
          example: rest_forbidden
        message:
          type: string
          description: Human-readable error message
          example: Sorry, you are not allowed to do that.
        data:
          type: object
          description: Additional data about the error
          properties:
            status:
              type: integer
              description: HTTP status code
              example: 403
    TermInput:
      type: object
      description: Input schema for creating or updating a term
      required:
      - name
      properties:
        name:
          type: string
          description: HTML title for the term
          example: Technology
        description:
          type: string
          description: HTML description of the term
          example: Technology-related posts
        slug:
          type: string
          description: An alphanumeric identifier
          example: technology
        parent:
          type: integer
          description: The parent term ID
          example: 0
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: wordpress_logged_in
      description: WordPress cookie authentication with nonce (X-WP-Nonce header required)
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Application Passwords (WordPress 5.6+)
    applicationPassword:
      type: http
      scheme: basic
      description: Application Passwords - generate per-application passwords from user profile in WordPress admin