Automattic Comments API

openapi: 3.2.0
info:
  title: Automattic Comments API
  x-derived-by: API Evangelist enrichment pipeline
  x-refined-note:
  - x-derived-from differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged comments across 3 of this provider''s published API definitions: automattic-wordpress-com-rest-v1-1-openapi.yml, automattic-wordpress-com-rest-v1-2-openapi.yml, automattic-wordpress-com-wp-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public-api.wordpress.com/rest/v1.1
- url: https://public-api.wordpress.com/rest/v1.2
- url: https://public-api.wordpress.com
security:
- bearerAuth: []
tags:
- name: comments
paths:
  /sites/{site}/comment-counts:
    get:
      operationId: getSitesBySiteCommentCounts
      summary: Get comment counts for each available status
      description: Get comment counts for each available status
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  all:
                    type: integer
                    description: Combined number of approved and unapproved comments
                  approved:
                    type: integer
                    description: Number of approved comments
                  pending:
                    type: integer
                    description: Number of unapproved comments
                  trash:
                    type: integer
                    description: Number of trash comments
                  spam:
                    type: integer
                    description: Number of spam comments
                  post_trashed:
                    type: integer
                    description: Number of comments whose parent post has been trashed
                  total_comments:
                    type: integer
                    description: Combined number of comments in each category
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      - name: post_id
        in: query
        required: false
        schema:
          type: integer
        description: post ID for filtering the comment counts by post
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/comment-history/{comment_ID}:
    get:
      operationId: getSitesBySiteCommentHistoryByCommentId
      summary: Get the audit history for given comment
      description: Get the audit history for given comment
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  comment_history:
                    type: array
                    items: {}
                    description: Array of arrays representing the comment history objects.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: comment_ID
        in: path
        required: true
        schema:
          type: integer
        description: The comment ID
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/comments/:
    get:
      operationId: getSitesBySiteComments
      summary: Get a list of recent comments.
      description: Get a list of recent comments.
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  found:
                    type: integer
                    description: The total number of comments found that match the request (ignoring limits, offsets, and pagination).
                  site_ID:
                    type: integer
                    description: The site ID
                  comments:
                    type: array
                    items: {}
                    description: An array of comment objects.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      - name: number
        in: query
        required: false
        schema:
          type: integer
        description: 'The number of comments to return.  Limit: 100. When using hierarchical=1, number refers to the number of top-level comments returned. Default: 20.'
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: 0-indexed offset. Not available if using hierarchical=1.
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Return the Nth 1-indexed page of comments.  Takes precedence over the offset parameter. When using hierarchical=1, pagination is a bit different.  See the note on the number parameter.
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
        description: 'DESC: (default) Return comments in descending order from newest to oldest.; ASC: Return comments in ascending order from oldest to newest.'
      - name: hierarchical
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: (BETA) Order the comment list hierarchically.'
      - name: after
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Return comments dated on or after the specified datetime. Not available if using hierarchical=1.
      - name: before
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Return comments dated on or before the specified datetime. Not available if using hierarchical=1.
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - any
          - comment
          - trackback
          - pingback
          - pings
        description: 'any: (default) Return all comments regardless of type.; comment: Return only regular comments.; trackback: Return only trackbacks.; pingback: Return only pingbacks.; pings: Return both trackbacks and pingbacks.'
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - approved
          - unapproved
          - spam
          - trash
          - all
        description: 'approved: (default) Return only approved comments.; unapproved: Return only comments in the moderation queue.; spam: Return only comments marked as spam.; trash: Return only comments in the trash.; all: Return comments of all statuses.'
      - name: author_wpcom_data
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default) Do not add wpcom_id and wpcom_login fields to comment author responses (default); true: Add wpcom_id and wpcom_login fields to comment author responses'
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/comments/{comment_ID}:
    get:
      operationId: getSitesBySiteCommentsByCommentId
      summary: Get a single comment.
      description: Get a single comment.
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The comment ID.
                  post:
                    type: object
                    description: A reference to the comment's post.
                  author:
                    type: object
                    description: The author of the comment.
                  date:
                    type: string
                    format: date-time
                    description: The comment's creation time.
                  URL:
                    type: string
                    format: uri
                    description: The full permalink URL to the comment.
                  short_URL:
                    type: string
                    format: uri
                    description: The wp.me short URL.
                  content:
                    type: string
                    description: context dependent.
                  raw_content:
                    type: string
                    description: Raw comment content.
                  status:
                    type: string
                    description: 'approved: The comment has been approved.; unapproved: The comment has been held for review in the moderation queue.; spam: The comment has been marked as spam.; trash: The comment is in the trash.'
                    enum:
                    - approved
                    - unapproved
                    - spam
                    - trash
                  parent:
                    type: string
                    description: A reference to the comment's parent, if it has one.
                  type:
                    type: string
                    description: 'comment: The comment is a regular comment.; trackback: The comment is a trackback.; pingback: The comment is a pingback.; review: The comment is a product review.'
                    enum:
                    - comment
                    - trackback
                    - pingback
                    - review
                  like_count:
                    type: integer
                    description: The number of likes for this comment.
                  i_like:
                    type: boolean
                    description: Does the current user like this comment?
                  meta:
                    type: object
                    description: Meta data
                  can_moderate:
                    type: boolean
                    description: Whether current user can moderate the comment.
                  i_replied:
                    type: boolean
                    description: Has the current user replied to this comment?
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: comment_ID
        in: path
        required: true
        schema:
          type: integer
        description: The comment ID
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
    post:
      operationId: postSitesBySiteCommentsByCommentId
      summary: Edit a comment.
      description: Edit a comment.
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The comment ID.
                  post:
                    type: object
                    description: A reference to the comment's post.
                  author:
                    type: object
                    description: The author of the comment.
                  date:
                    type: string
                    format: date-time
                    description: The comment's creation time.
                  URL:
                    type: string
                    format: uri
                    description: The full permalink URL to the comment.
                  short_URL:
                    type: string
                    format: uri
                    description: The wp.me short URL.
                  content:
                    type: string
                    description: context dependent.
                  raw_content:
                    type: string
                    description: Raw comment content.
                  status:
                    type: string
                    description: 'approved: The comment has been approved.; unapproved: The comment has been held for review in the moderation queue.; spam: The comment has been marked as spam.; trash: The comment is in the trash.'
                    enum:
                    - approved
                    - unapproved
                    - spam
                    - trash
                  parent:
                    type: string
                    description: A reference to the comment's parent, if it has one.
                  type:
                    type: string
                    description: 'comment: The comment is a regular comment.; trackback: The comment is a trackback.; pingback: The comment is a pingback.; review: The comment is a product review.'
                    enum:
                    - comment
                    - trackback
                    - pingback
                    - review
                  like_count:
                    type: integer
                    description: The number of likes for this comment.
                  i_like:
                    type: boolean
                    description: Does the current user like this comment?
                  meta:
                    type: object
                    description: Meta data
                  can_moderate:
                    type: boolean
                    description: Whether current user can moderate the comment.
                  i_replied:
                    type: boolean
                    description: Has the current user replied to this comment?
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: comment_ID
        in: path
        required: true
        schema:
          type: integer
        description: The comment ID
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads data from the endpoints found in the ''meta'' part of the response. Comma-separated list. Example: meta=site,likes'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title'
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: An optional JSONP callback function.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                author:
                  type: string
                  description: The comment author's name.
                author_email:
                  type: string
                  description: The comment author's email.
                author_url:
                  type: string
                  description: The comment author's URL.
                content:
                  type: string
                  description: The comment text.
                date:
                  type: string
                  format: date-time
                  description: The comment's creation time.
                status:
                  type: string
                  description: 'approved: (default) Approve the comment.; unapproved: Remove the comment from public view and send it to the moderation queue.; spam: Mark the comment as spam.; unspam: Unmark the comment as spam. Will attempt to set it to the previous status.; trash: Send a comment to the trash if trashing is enabled (see constant: EMPTY_TRASH_DAYS).; untrash: Untrash a comment. Only works when the comment is in the trash.'
                  enum:
                  - approved
                  - unapproved
                  - spam
                  - unspam
                  - trash
                  - untrash
    servers:
    - url: https://public-api.wordpress.com/rest/v1.1
  /sites/{site}/comments/{comment_ID}/delete:
    post:
      operationId: postSitesBySiteCommentsByCommentIdDelete
      summary: Delete a comment.
      description: Delete a comment.
      tags:
      - comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    type: integer
                    description: The comment ID.
                  post:
                    type: object
                    description: A reference to the comment's post.
                  author:
                    type: object
                    description: The author of the comment.
                  date:
                    type: string
                    format: date-time
                    description: The comment's creation time.
                  URL:
                    type: string
                    format: uri
                    description: The full permalink URL to the comment.
                  short_URL:
                    type: string
                    format: uri
                    description: The wp.me short URL.
                  content:
                    type: string
                    description: context dependent.
                  raw_content:
                    type: string
                    description: Raw comment content.
                  status:
                    type: string
                    description: 'approved: The comment has been approved.; unapproved: The comment has been held for review in the moderation queue.; spam: The comment has been marked as spam.; trash: The comment is in the trash.; deleted: The comment has been deleted permanently.'
                    enum:
                    - approved
                    - unapproved
                    - spam
                    - trash
                    - deleted
                  parent:
                    type: string
                    description: A reference to the comment's parent, if it has one.
                  type:
                    type: string
                    description: 'comment: The comment is a regular comment.; trackback: The comment is a trackback.; pingback: The comment is a pingback.; review: The comment is a product review.'
                    enum:
                    - comment
                    - trackback
                    - pingback
                    - review
                  like_count:
                    type: integer
                    description: The number of likes for this comment.
                  i_like:
                    type: boolean
                    description: Does the current user like this comment?
                  meta:
                    type: object
                    description: Meta data
                  can_moderate:
                    type: boolean
                    description: Whether current user can moderate the comment.
                  i_replied:
                    type: boolean
                    description: Has the current user replied to this comment?
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: Site ID or domain
      - name: comment_ID
        in: path
        required: true
        schema:
          type: integer
        description: The comment ID
      - name: context
        in: query
        required: false
        schema:
          type: string
          enum:
          - display
          - edit
        description: 'display: (default) Formats the output as HTML for display.  Shortcodes are parsed, paragraph tags are added, etc..; edit: Formats the output for editing.  Shortcodes are left unparsed, significant whitespace is kept, etc..'
      - name: http_envelope
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code.  Setting this parameter will force the HTTP status code to always be 200.  The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.'
      - name: pretty
        in: query
        required: false
        schema:
          type: boolean
        description: 'false: (default); true: Output pretty JSON'
      - name: meta
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. Loads da

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/automattic/refs/heads/main/openapi/automattic-comments-api-openapi.yml