openapi: 3.0.3
info:
  title: WordPress REST Block Types Comments 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: Comments
  description: Manage WordPress comments
paths:
  /wp/v2/comments:
    get:
      operationId: listComments
      summary: WordPress List Comments
      description: Retrieves a collection of comments. Public endpoint returns approved comments.
      tags:
      - Comments
      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 to be returned.
        schema:
          type: integer
          default: 10
        example: 10
      - name: post
        in: query
        description: Limit result set to comments assigned to specific post IDs.
        schema:
          type: array
          items:
            type: integer
        example:
        - 123
      - name: status
        in: query
        description: Limit result set to comments assigned a specific status.
        schema:
          type: string
          default: approve
        example: approve
      responses:
        '200':
          description: A list of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              examples:
                ListComments200Example:
                  summary: Default listComments 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    post: 123
                    parent: 0
                    author: 0
                    author_name: John Doe
                    author_email: john@example.com
                    date: '2026-04-16T08:00:00'
                    content:
                      rendered: <p>Great post!</p>
                    status: approved
                    type: comment
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createComment
      summary: WordPress Create Comment
      description: Creates a new comment on a post.
      tags:
      - Comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentInput'
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              examples:
                CreateComment201Example:
                  summary: Default createComment 201 response
                  x-microcks-default: true
                  value:
                    id: 2
                    post: 123
                    status: approved
                    author_name: Jane Smith
                    content:
                      rendered: <p>Thanks for sharing!</p>
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RenderedContent:
      type: object
      description: A rendered content object containing raw and rendered versions
      properties:
        rendered:
          type: string
          description: The HTML rendered version of the content
          example: <p>Hello World</p>
        protected:
          type: boolean
          description: Whether the content is protected with a password
          example: false
    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
    CommentInput:
      type: object
      description: Input schema for creating a comment
      required:
      - post
      - content
      properties:
        post:
          type: integer
          description: The ID of the associated post
          example: 123
        parent:
          type: integer
          description: The ID for the parent of the comment
          example: 0
        author_name:
          type: string
          description: Display name for the comment author
          example: Jane Smith
        author_email:
          type: string
          format: email
          description: Email for the comment author
          example: jane@example.com
        content:
          type: string
          description: The content for the comment
          example: Thanks for sharing!
    Comment:
      type: object
      description: A WordPress comment object
      properties:
        id:
          type: integer
          description: Unique identifier for the comment
          example: 1
        post:
          type: integer
          description: The ID of the associated post
          example: 123
        parent:
          type: integer
          description: The ID for the parent of the comment
          example: 0
        author:
          type: integer
          description: The ID of the user object, if author was a user
          example: 0
        author_name:
          type: string
          description: Display name for the comment author
          example: John Doe
        author_email:
          type: string
          format: email
          description: Email address for the comment author
          example: john@example.com
        date:
          type: string
          format: date-time
          description: The date the comment was published
          example: '2026-04-16T08:00:00'
        content:
          $ref: '#/components/schemas/RenderedContent'
        status:
          type: string
          description: State of the comment
          enum:
          - approved
          - unapproved
          - hold
          - spam
          - trash
          example: approved
        type:
          type: string
          description: Type of the comment
          example: comment
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BadRequest400Example:
              summary: Bad request example
              x-microcks-default: true
              value:
                code: rest_invalid_param
                message: Invalid parameter.
                data:
                  status: 400
  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