Where to Find the API Documentation for Motrix

Motrix maintains its API documentation across multiple locations, with the MDXP (Motrix Download eXchange Protocol) JSON-RPC specification detailed in the main repository's README and Docker docs, while the Plugin SDK references live in a separate dedicated repository.

The agalwood/Motrix repository serves as the central hub for this open-source download manager, but the API documentation for Motrix is distributed between the core codebase and external packages depending on whether you are integrating with the download engine or developing sandboxed extensions.

Understanding Motrix's Dual API Architecture

Motrix exposes two distinct programming interfaces that serve different integration scenarios. Understanding which surface to use depends on whether you need direct download control or plugin capabilities.

MDXP: The Core Download Protocol

The MDXP (Motrix Download eXchange Protocol) is a JSON-RPC 2.0-based HTTP/SSE service that forms the backbone of Motrix's remote control capabilities. According to the source code in README.md, this protocol runs on port 16801 while the Web UI occupies port 8080, allowing headless server deployments to accept download commands from CLI clients, browser extensions, and remote agents.

The protocol supports core operations including add, list, pause, and delete tasks, with events streamed via Server-Sent Events (SSE). The concrete HTTP endpoint configuration and environment variables are documented in docs/docker-server.md at lines 124-131.

Plugin SDK: The Extension Interface

For developers building sandboxed extensions, Motrix provides a separate Plugin SDK that operates within a QuickJS sandbox. This TypeScript API exposes a virtual module motrix:plugin-api that plugins use to interact with the running Motrix instance, offering lifecycle hooks, sandboxed commands, and settings access.

Unlike MDXP, which operates over HTTP, the Plugin SDK runs inside Motrix's renderer process according to .claude/rules/bridge.md, with the full TypeScript definitions and scaffolding tools maintained in the external plugin-sdk repository.

Locating the Official Documentation Sources

The API documentation for Motrix is not centralized in a single location. Instead, it spans the main repository and specialized external resources based on the integration type.

Core Protocol References

The primary entry point for MDXP documentation resides in the repository's README.md, which outlines the protocol name, port allocations (8080 for Web UI, 16801 for MDXP), and links to the dedicated MDXP package. For deployment-specific details including Docker environment variables and network configuration, consult docs/docker-server.md, which describes how the MDXP service binds to interfaces and handles HTTP requests.

Plugin Development Resources

Plugin documentation lives entirely in a separate repository at motrixapp/plugin-sdk. This resource contains the complete TypeScript API documentation, manifest schema definitions, and the create-motrix-plugin CLI tool for scaffolding new extensions.

Working with the MDXP JSON-RPC API

To interact with Motrix programmatically, you send JSON-RPC 2.0 requests to the MDXP endpoint. The service accepts POST requests at /mdxp with method calls like add, list, and remove.

Direct HTTP Integration

When Motrix runs in server mode (or when accessing the local instance), the MDXP endpoint accepts standard JSON-RPC payloads:

# Add a new download task via MDXP

curl -X POST http://localhost:16801/mdxp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "add",
    "params": {
      "url": "https://example.com/file.iso",
      "saveDir": "/home/user/Downloads"
    }
  }'

This endpoint validates requests against the Zod schemas defined in the external mdxp repository, ensuring type safety for parameters including URLs, save directories, and task options.

Using the Official CLI

The @motrix/cli package abstracts the MDXP protocol, handling service discovery and request formatting automatically:

# Install the CLI globally

npm install -g @motrix/cli

# Add a download task

motrix add https://example.com/file.iso --save-dir ~/Downloads

# Monitor progress via NDJSON stream

motrix watch --stats

The CLI references the MDXP bridge implementation described in .claude/rules/bridge.md to communicate with both local Electron instances and remote Docker deployments.

Developing Plugins with the TypeScript SDK

Plugins run inside a QuickJS sandbox and receive a virtual motrix:plugin-api module injected at runtime. This approach isolates extension code from the main process while providing controlled access to download functionality.

Basic Plugin Structure

Create a plugin by implementing the SDK's interface:

// src/index.ts
import { onTaskCreated, addCommand } from 'motrix:plugin-api';

onTaskCreated(async (task) => {
  console.log('New task detected:', task.id);
});

addCommand('hello', async () => {
  return 'Hello from my Motrix plugin!';
});

The package.json in the main Motrix repository declares the @motrix/plugin-sdk dependency, which defines these runtime hooks. Full scaffolding instructions and linting tools are available in the external SDK repository.

Key Source Files for API Reference

When examining the API documentation for Motrix at the source level, these files contain the authoritative definitions:

• README.md — Central overview documenting MDXP ports, protocol name, CLI quick-start, and Plugin SDK links
• docs/docker-server.md — Complete MDXP service configuration including environment variables, port bindings (16801), and HTTP endpoint specifications
• .claude/rules/bridge.md — MDXP bridge lifecycle documentation explaining how the Electron renderer communicates with the download server
• package.json — Declares @motrix/mdxp and @motrix/plugin-sdk versions used by the current release
• src/renderer/components/desktop-kit/README.md — UI component API documentation for renderer extensions

Summary

• Motrix provides two APIs: MDXP for HTTP-based download control (port 16801) and the Plugin SDK for sandboxed TypeScript extensions
• MDXP documentation resides in the main repository's README.md and docs/docker-server.md, with full schema definitions in the external mdxp repository
• Plugin documentation is maintained separately in the plugin-sdk repository, offering TypeScript definitions and CLI scaffolding
• JSON-RPC 2.0 powers the core protocol, accepting POST requests to /mdxp with methods like add, list, and remove
• QuickJS sandboxing isolates plugins, which access Motrix features through the injected motrix:plugin-api virtual module

Frequently Asked Questions

What is the difference between MDXP and the Plugin SDK?

MDXP is a network-facing JSON-RPC protocol running on port 16801 for external applications to control downloads, while the Plugin SDK is an in-process TypeScript API for extensions running inside Motrix's QuickJS sandbox. Use MDXP for CLI tools and integrations; use the Plugin SDK for feature extensions that need UI integration.

How do I access the MDXP API from an external application?

Send HTTP POST requests to http://localhost:16801/mdxp with JSON-RPC 2.0 payloads containing method (e.g., add, list) and params objects. For remote servers, configure the host and port using the environment variables documented in docs/docker-server.md.

Where are the TypeScript definitions for Motrix plugins?

The complete TypeScript API definitions, manifest schemas, and type declarations are located in the external motrixapp/plugin-sdk repository, not in the main agalwood/Motrix codebase. This repository also contains the create-motrix-plugin CLI tool.

Can I run Motrix in headless server mode without the GUI?

Yes. The Docker server configuration documented in docs/docker-server.md allows running Motrix as a headless service exposing only the MDXP API on port 16801 and the Web UI on port 8080, enabling remote download management without the Electron frontend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}