API Integration Guide
Base URL, mod listing contract and error format for the Deadlock Mod Manager HTTP API
The API Reference documents each HTTP route with its request and response schema and lets you send test requests. This page covers the base URL, the mod routes and the error format.
Base URL
HTTP routes are served under https://api.deadlockmods.app/api. A route documented as GET /v2/mods is requested at https://api.deadlockmods.app/api/v2/mods. The OpenAPI specification is published at https://api.deadlockmods.app/docs/openapi.json.
Authentication
Mod, download and status routes are public:
const response = await fetch("https://api.deadlockmods.app/api/v2/mods");
const mods = await response.json();Routes that read or change account data, such as profile backups, require a signed-in session.
Rate Limiting
Rate limits apply per route and per client IP. Limited routes use a fixed window:
| Route | Limit |
|---|---|
POST /v2/sync, POST /v2/sync/{id} | 3 requests per 60 seconds |
GET /v2/mod-authors/{id} | 60 requests per 60 seconds |
GET /v2/servers, GET /v2/servers/facets, GET /v2/servers/{id}, POST /v2/servers/{id}/resolve-mods | 60 requests per 60 seconds |
PUT /v2/profile-backups | 60 requests per 10 minutes |
Other routes, including the mod listing, have no application rate limit. Limited routes return these headers, where RateLimit-Reset is the number of seconds until the window resets:
RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 42A rejected request returns HTTP 429 with code TOO_MANY_REQUESTS and a Retry-After header in seconds.
Mods
The mod routes return data defined by ModDtoSchema and ModDownloadDtoSchema in packages/shared/src/schemas/mod.schemas.ts.
List mods
GET /v2/modsReturns every mod as a JSON array. The route takes no query parameters: there is no pagination, search, filtering or sorting, so filter the array on the client. GET /v1/mods returns the same array.
Response, with one element shown and optional fields omitted:
[
{
"id": "mod_01jhq6v3x9e8s7r6t5y4u3i2o1",
"remoteId": "512345",
"name": "Example Skin",
"description": "A recolor for Haze.",
"remoteUrl": "https://gamebanana.com/mods/512345",
"category": "Skins",
"likes": 42,
"author": "ExampleAuthor",
"modAuthorId": null,
"downloadable": true,
"remoteAddedAt": "2026-01-10T08:00:00.000Z",
"remoteUpdatedAt": "2026-01-20T14:45:00.000Z",
"tags": [],
"images": ["https://images.gamebanana.com/img/ss/mods/example.jpg"],
"hero": "Haze",
"isAudio": false,
"isMap": false,
"audioUrl": null,
"downloadCount": 1542,
"isNSFW": false,
"filesUpdatedAt": "2026-01-20T14:45:00.000Z",
"createdAt": "2026-01-10T09:00:00.000Z",
"updatedAt": "2026-01-20T15:00:00.000Z"
}
]Mod routes send Cache-Control: public, max-age=3600, so the list can be cached for an hour.
Get a mod
GET /v2/mods/{id}Returns one mod object in the same shape. {id} is the GameBanana mod ID (remoteId), not the internal id. An unknown ID returns 404. GET /v1/mods/{id} behaves the same way.
Mod downloads
GET /v2/mods/{id}/downloadsReturns { "downloads": [...], "count": n }. Each download has url, size in bytes, name, description, createdAt, updatedAt and md5Checksum. GET /v1/mods/{id}/download returns an array that contains only the largest file. Both routes return 404 when the mod or its files are not found.
Desktop Integration API
The desktop frontend calls Rust through Tauri commands. Commands are registered in invoke_handler in apps/desktop/src-tauri/src/lib.rs and implemented in apps/desktop/src-tauri/src/commands/. Rust payload types that derive ts-rs are exported to apps/desktop/src/types/generated/; run pnpm --filter desktop generate-types after changing one.
Installing and launching mods
Use the existing hooks instead of invoking these commands from new code. useInstall in apps/desktop/src/hooks/use-install.ts installs a downloaded mod into the active profile and resolves file conflicts with the user. useLaunch in apps/desktop/src/hooks/use-launch.ts runs the pre-launch checks and starts the game.
Commands that change files in the game install go through invokeGuarded from apps/desktop/src/lib/game-guard.ts. The backend refuses them while Deadlock is running; invokeGuarded shows the warning dialog and, if the user continues, retries once with a one-time permit. This is how use-model-conflict-install.ts calls install_mod:
const result = await invokeGuarded<InstallableMod>("install_mod", {
deadlockMod: {
id: mod.remoteId,
name: mod.name,
is_map: mod.isMap,
file_tree: mod.file_tree,
},
profileFolder,
replaceConflictingMods,
allowConflictingMods: [...allow, ...protectedRequirements],
bisectOriginalEnabled,
keptChoices,
});install_mod enables the VPKs of a mod that is already in the mod store. It does not take an archive path or backup options.
Events
Some long operations report progress through Tauri events. For example, the addons backup manager emits backup-progress, which apps/desktop/src/components/settings/addons-backup-management.tsx subscribes to with listen from @tauri-apps/api/event. Search the Rust sources for .emit( to find an event's name and payload.
Error Handling
Errors use oRPC's JSON body, and the HTTP status matches status:
{
"defined": false,
"code": "NOT_FOUND",
"status": 404,
"message": "Not Found"
}Invalid input returns 400 with code BAD_REQUEST.
Desktop Application Errors
Tauri commands reject with an object that has a kind field, such as gameNotFound or gameRunning, and a message. ErrorKind and the isTauriError type guard live in apps/desktop/src/types/tauri.ts.
Support and Resources
Interactive API Documentation
Browse and test API endpoints live
API Status
Check API availability and performance
Discord Community
Get help from other developers
GitHub Issues
Report API issues and bugs
OpenAPI Specification
Machine-readable API specification
Need Help?
If you have questions about the API or need help integrating with Deadlock Mod Manager, please join our Discord community or create an issue on GitHub.