Comments

A comment belongs to a download. Comments are the add-on's native discussion surface. They are independent of the optional thread auto-creation feature, and both can be active at once. Routes mount at /api/mc-dm-comments/.

List comments

GET /api/mc-dm-comments/

Scope: mc_dm_download:read.

Parent filter: download_id is required for non-super-user keys.

Param	Type	Notes
download_id	uint	Required for user keys. Optional for super-user keys.
since	ISO 8601	Filters by comment_date.

Non-super-user keys are forced to comment_state=visible. Moderated and deleted comments are hidden. Super-user keys see every state.

Order whitelist: comment_date, last_edit_date. Default comment_date desc.

Example

curl -H "XF-Api-Key: $KEY" \
    "https://example.com/api/mc-dm-comments/?download_id=42&order=comment_date&direction=asc"

Response

{
    "comments": [
        {
            "comment_id": 700,
            "download_id": 42,
            "user_id": 17,
            "username": "alice",
            "comment_date": 1746210000,
            "message": "Works great on PHP 8.3.",
            "comment_state": "visible",
            "last_edit_date": 0,
            "edit_count": 0,
            "is_visible": true
        }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 5, "last_page": 1 }
}

Get a single comment

GET /api/mc-dm-comments/<comment_id>/

Scope: mc_dm_download:read.

Permission: the visitor must pass canView on the comment.

Response: { "comment": { ... } }.

Create a comment

POST /api/mc-dm-comments/

Scope: mc_dm_download:write.

Permission: canViewComments on the parent download. The create service performs its own deeper post-permission and rate-limit checks.

Field	Type	Notes
download_id	uint	Required.
message	string	Required. BB code permitted.

Example

curl -X POST -H "XF-Api-Key: $KEY" \
    -d "download_id=42" \
    -d "message=Confirmed working on PHP 8.3." \
    https://example.com/api/mc-dm-comments/

Response: { "comment": { ... } }.

If the category requires comment approval and the visitor doesn't bypass it, comment_state returns as moderated.

Update a comment

PUT /api/mc-dm-comments/<comment_id>/

Scope: mc_dm_download:write.

Permission: canEdit on the comment.

Field	Type	Notes
message	string	Required. An empty string is rejected with HTTP 422.

The Edit service writes an edit-history row when the visitor's role triggers it. This uses XF native EditHistory wiring.

curl -X PUT -H "XF-Api-Key: $KEY" \
    -d "message=Confirmed working on PHP 8.3 and 8.4." \
    https://example.com/api/mc-dm-comments/700/

Response: { "comment": { ... } }.

Delete a comment

DELETE /api/mc-dm-comments/<comment_id>/

Scope: mc_dm_download:write always. mc_dm_download:delete_hard additionally when hard=1.

Permission: canDelete on the comment.

Param	Effect
hard	1 = irreversibly remove the row. Default 0 = soft delete (sets comment_state='deleted').
reason	Optional moderator-log reason.

curl -X DELETE -H "XF-Api-Key: $KEY" \
    -d "reason=Off-topic" \
    https://example.com/api/mc-dm-comments/700/

Response: { "success": true }.

Verbose mode (?with=full)

Adds:

Field	Type	Notes
can_view	bool	Visitor permission.
can_edit	bool	Visitor permission.
can_delete	bool	Visitor permission.