Categories

Categories are the add-on's content tree. They use XF\Permission\TreeContentPermissions for inherited per-node permissions. Read endpoints are scoped under mc_dm_category:*. Write endpoints additionally require admin rights. Routes mount at /api/mc-dm-categories/.

List categories

GET /api/mc-dm-categories/

Scope: mc_dm_category:read.

No parent filter is required. Rows the visitor cannot view are dropped from the page.

Order whitelist: display_order, title, download_count. Default display_order desc. There is no since support.

Example

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

Response

{
    "categories": [
        {
            "category_id": 4,
            "parent_category_id": 0,
            "title": "Plugins",
            "description": "Server-side plugins.",
            "display_order": 10,
            "download_count": 87,
            "fa_icon": "fa-puzzle-piece",
            "icon_color": "#3a7bd5",
            "view_url": "https://example.com/downloads/categories/plugins.4/"
        }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 6, "last_page": 1 }
}

Get a single category

GET /api/mc-dm-categories/<category_id>/

Scope: mc_dm_category:read.

Permission: the visitor must pass canView on the category.

Response: { "category": { ... } }.

Create a category (admin)

POST /api/mc-dm-categories/

Scope: mc_dm_category:write.

Permission: super-user key, or an admin-flagged user.

Field	Type	Notes
title	string	Required.
description	string	Optional.
parent_category_id	uint	Optional. 0 for top-level.
display_order	uint	Optional.
fa_icon	string	Optional Font Awesome icon name (e.g. fa-puzzle-piece).
icon_color	string	Optional CSS hex colour.

Example

curl -X POST -H "XF-Api-Key: $KEY" \
    -d "title=Themes" \
    -d "description=Style customisations." \
    -d "parent_category_id=0" \
    -d "display_order=20" \
    -d "fa_icon=fa-paint-brush" \
    https://example.com/api/mc-dm-categories/

Response: { "category": { ... } }.

Configuration knobs that govern category behaviour at runtime (versioning, multi-file, max sizes, allowed file types, comment and thread modes, approval, and so on) are not exposed on POST. Set them via PUT after creation, or via the AdminCP.

Update a category (admin)

PUT /api/mc-dm-categories/<category_id>/

Scope: mc_dm_category:write.

Permission: super-user key, or an admin-flagged user.

Field	Type
title	string
description	string
parent_category_id	uint
display_order	uint
fa_icon	string
icon_color	string
require_approval	bool
enable_versioning	bool
allow_multi_file	bool
max_files_per_version	uint
allowed_file_types	string (comma-separated extensions)

Omitted fields are untouched.

curl -X PUT -H "XF-Api-Key: $KEY" \
    -d "require_approval=1" \
    -d "max_files_per_version=5" \
    https://example.com/api/mc-dm-categories/4/

Response: { "category": { ... } }.

Delete a category (admin)

DELETE /api/mc-dm-categories/<category_id>/

Scope: mc_dm_category:write and mc_dm_category:delete_hard.

Permission: super-user key, or an admin-flagged user.

Categories have no soft-delete state. The hard=1 flag is required explicitly to guard against accidental destructive calls. Without it the request fails HTTP 422 with code mc_dm_api_error.category_hard_delete_required.

curl -X DELETE -H "XF-Api-Key: $KEY" \
    -d "hard=1" \
    https://example.com/api/mc-dm-categories/4/

Response: { "success": true }.

Deleting a category with downloads cascades through the entity's _preDelete and _postDelete lifecycle. Downloads are reassigned or removed per the configured policy. Use with care.

Verbose mode (?with=full)

Adds:

Field	Type	Notes
require_approval	bool
max_team_members	int
max_files_per_version	int
max_file_size	int	Bytes.
max_version_size	int	Bytes.
max_download_size	int	Bytes.
allowed_file_types	string
preview_text_enabled	bool
preview_image_enabled	bool