# Where to Find the API Documentation for Motrix

> Discover where to find the API documentation for Motrix. Locate MDXP JSON-RPC specs in the main repo README and Docker docs, and Plugin SDK references in a dedicated repository.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: api-reference
- Published: 2026-08-20

---

**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](https://github.com/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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/.claude/rules/bridge.md), with the full TypeScript definitions and scaffolding tools maintained in the external [plugin-sdk repository](https://github.com/motrixapp/plugin-sdk).

## 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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/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](https://github.com/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:

```bash

# 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](https://github.com/motrixapp/mdxp), 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:

```bash

# 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`](https://github.com/agalwood/Motrix/blob/main/.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:

```typescript
// 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`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/README.md)** — Central overview documenting MDXP ports, protocol name, CLI quick-start, and Plugin SDK links
- **[`docs/docker-server.md`](https://github.com/agalwood/Motrix/blob/main/docs/docker-server.md)** — Complete MDXP service configuration including environment variables, port bindings (16801), and HTTP endpoint specifications
- **[`.claude/rules/bridge.md`](https://github.com/agalwood/Motrix/blob/main/.claude/rules/bridge.md)** — MDXP bridge lifecycle documentation explaining how the Electron renderer communicates with the download server
- **[`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json)** — Declares `@motrix/mdxp` and `@motrix/plugin-sdk` versions used by the current release
- **[`src/renderer/components/desktop-kit/README.md`](https://github.com/agalwood/Motrix/blob/main/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`](https://github.com/agalwood/Motrix/blob/main/README.md) and [`docs/docker-server.md`](https://github.com/agalwood/Motrix/blob/main/docs/docker-server.md), with full schema definitions in the external [mdxp](https://github.com/motrixapp/mdxp) repository
- **Plugin documentation** is maintained separately in the [plugin-sdk](https://github.com/motrixapp/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`](https://github.com/agalwood/Motrix/blob/main/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](https://github.com/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`](https://github.com/agalwood/Motrix/blob/main/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.