REST API

The REST API exposes five resource families: downloads, versions, files, comments, and categories. Routes are flat and top-level (XF idiom). Authenticate every request with an XF native API key.

Authentication

Pass the API key on every request:

XF-Api-Key: <key>

Configure keys in AdminCP > Setup > API keys.

Two key types are supported:

• Super-user keys bypass scope and permission checks. They impersonate the user named in the XF-Api-User header. If the header is omitted, the request runs unattributed.
• User keys are scoped to a single user. The API scope and the user's per-category permission must both allow the operation.

Scopes

Scope	Grants
mc_dm_download:read	List and get downloads, versions, files, comments.
mc_dm_download:write	Create, update, and soft-delete downloads, versions, files, comments.
mc_dm_download:delete_hard	Hard-delete (?hard=1) the same.
mc_dm_category:read	List and get categories.
mc_dm_category:write	Create and update categories (admin only).
mc_dm_category:delete_hard	Hard-delete categories (admin only).

Hard-delete endpoints require both the matching *:write scope and the *:delete_hard scope. The hard-delete scope alone is not sufficient.

Base URLs

• /api/mc-dm-downloads/
• /api/mc-dm-versions/
• /api/mc-dm-files/
• /api/mc-dm-comments/
• /api/mc-dm-categories/

The /api/ prefix is XF's standard API mount. The mc-dm-* segment is the add-on's API route prefix.

Common list parameters

Param	Effect
page	1-indexed. Default 1.
per_page	Default 20, max 100. Out-of-range values are clamped.
order	Per-resource whitelist. See each resource page.
direction	asc or desc. Default desc.
since	ISO 8601 datetime. Filters the list to records newer than the timestamp on the resource's primary date column. Resource pages note whether since is supported.
with	default (normal verbosity) or full (verbose).

Versions, files, and comments require a parent filter for non-super-user keys. Use download_id for versions and comments, version_id for files. Without it the request fails with HTTP 400.

Pagination shape

Every list response carries:

{
    "<resource>": [],
    "pagination": { "page": 1, "per_page": 20, "total": 137, "last_page": 7 }
}

<resource> is downloads, versions, files, comments, or categories.

Error shape

{
    "errors": [
        { "code": "mc_dm_api_error.missing_scope", "message": "...", "params": {} }
    ]
}

HTTP status codes:

Status	Meaning
400	Validation (e.g. missing parent filter).
401	No API key supplied.
403	Scope denied or visitor lacks per-category permission.
404	Record not found.
422	Input failed validation, gate, or processor (e.g. file rejected by a magic-byte check).

Verbose mode

?with=full switches the entity from VERBOSITY_NORMAL to VERBOSITY_VERBOSE. The extra fields are listed on each resource page.

Audit log

All write operations write a row to xf_mc_dm_audit_log tagged with via=api. The row also stores the API key id (when present), the user id, the IP, and a small details JSON payload. The audit viewer lives at AdminCP > Tools > Downloads audit log.