Developer Resources

API Reference - ModNexus

The Universal Mod Distribution Engine

ModNexus REST API architecture and endpoint routing diagram

Core Endpoints

Interact with the ModNexus catalog, handle binary payloads, and sync user preferences via standardized REST routes. All requests must target https://api.modnexus.com/v2/.

GET /mods/{slug}/metadata

Retrieve version history, dependency trees, and compatibility flags for a specific mod.

Request: GET /mods/tactical-reloads-overhaul/metadata

Response:

{
  "status": 200,
  "data": {
    "id": "mn_849201",
    "name": "Tactical Reloads Overhaul",
    "version": "3.1.4",
    "engine": "Unity 2022.3 LTS",
    "downloads": 142890,
    "dependencies": ["mn_core_loader", "mn_audio_ext"]
  }
}

POST /mods/upload

Submit a new build or patch. Requires multipart/form-data with a signed manifest.

Request: POST /mods/upload Content-Type: multipart/form-data

Response:

{
  "status": 201,
  "data": {
    "upload_id": "up_f8a9c21d",
    "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
    "scan_status": "clean",
    "publish_url": "/mods/tactical-reloads-overhaul/3.1.4"
  }
}

PATCH /users/{id}/subscriptions

Toggle auto-update preferences or manage premium tier access for mod creators.

Request: PATCH /users/usr_992041/subscriptions

Response:

{
  "status": 200,
  "data": {
    "user_id": "usr_992041",
    "auto_update": true,
    "premium_tier": "patron",
    "synced_at": "2024-05-12T14:30:00Z"
  }
}

Authentication & Authorization

ModNexus uses OAuth 2.0 with JWT bearer tokens for stateless session management. Read-only endpoints accept public API keys, while write operations require scoped credentials.

Include your token in the Authorization header. Tokens expire after 3600 seconds and must be refreshed via the /oauth/token endpoint. Scope restrictions enforce principle of least privilege:

read:mods – Access public metadata and download statistics
write:uploads – Publish binaries and update version manifests
admin:subscriptions – Manage billing tiers and user entitlements

Example header payload:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfOTkyMDQxIiwic2NvcGUiOiJyZWFkOm1vZHMiLCJleHAiOjE3MTU2MDI4MDB9.K5x...

Rate Limits & Throttling

To maintain catalog integrity and prevent scraping, ModNexus enforces sliding window rate limits per API key. Exceeding thresholds returns 429 Too Many Requests with retry guidance.

Standard Tier

120 requests per minute for metadata queries. Upload endpoints capped at 15 concurrent connections. Suitable for indie tools and local launchers.

Enterprise Tier

1,200 requests per minute with dedicated IP allowlists. Burst allowance of 500 requests for bulk sync operations. Required for studio pipelines and CDN integrations.

Response Headers

Monitor quota consumption via standard headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 84
X-RateLimit-Reset: 1715599200
Retry-After: 42