# Modrinth Minecraft Mods API
> Live mod-platform stats from Modrinth, the open Minecraft content platform — no key, nothing stored. The adoption-and-community view of the Minecraft modding ecosystem: how much each mod, modpack, shader or resource pack is downloaded and followed, and which projects are most popular, distinct from the other developer-ecosystem and gaming APIs in the catalogue. The project endpoint returns a single project in full — total downloads, followers, type, categories, supported game versions and loaders, client/server sides and license. The search endpoint searches projects, filterable by type (mod, modpack, shader, resource pack, data pack) and sortable by downloads or follows, each with its download and follower count. The versions endpoint returns a project's recent releases with per-version downloads, supported game versions and loaders. Build mod dashboards, popularity trackers, "is this mod maintained" widgets and modpack browsers on top of real Modrinth data. Look up a project by its slug (sodium, iris, fabric-api); downloads are the headline popularity metric.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/modrinth-api/..."
```

## Pricing
- **Free** (Free) — 26,000 calls/Mo, 3 req/s
- **Starter** ($4/Mo) — 340,000 calls/Mo, 10 req/s
- **Pro** ($14/Mo) — 1,450,000 calls/Mo, 25 req/s
- **Scale** ($32/Mo) — 5,200,000 calls/Mo, 55 req/s

## Endpoints

### Project

#### `GET /v1/project` — A project in full

**Parameters:**
- `slug` (query, required, string) — Project slug Example: `sodium`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/project?slug=sodium"
```

**Response:**
```json
{
    "data": {
        "url": "https://modrinth.com/mod/sodium",
        "slug": "sodium",
        "title": "Sodium",
        "source": "Modrinth",
        "license": "LicenseRef-Polyform-Shield-1.0.0",
        "loaders": [
            "fabric",
            "neoforge",
            "quilt"
        ],
        "updated": "2026-06-12T00:47:33.259264Z",
        "downloads": 166010755,
        "followers": 37192,
        "published": "2021-01-03T00:53:34.185936Z",
        "categories": [
            "optimization"
        ],
        "client_side": "required",
        "server_side": "unsupported",
        "project_type": "mod",
        "latest_game_version": "26.2-rc-1",
        "supported_game_versions": 36
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:09.988Z",
        "request_id": "84042f4a-6135-4961-bdf1-4b9f6c4910ab"
    },
    "status": "ok",
    "message": "Project retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search projects

**Parameters:**
- `q` (query, required, string) — Search query Example: `shaders`
- `type` (query, optional, string) — mod, modpack, shader, resourcepack, datapack or plugin Example: `shader`
- `sort` (query, optional, string) — relevance (default), downloads, follows, newest or updated Example: `downloads`
- `limit` (query, optional, string) — Max results (1-25) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/search?q=shaders&type=shader&sort=downloads&limit=10"
```

**Response:**
```json
{
    "data": {
        "sort": "downloads",
        "type": "shader",
        "count": 10,
        "query": "shaders",
        "total": 156,
        "source": "Modrinth",
        "results": [
            {
                "slug": "complementary-reimagined",
                "title": "Complementary Shaders - Reimagined",
                "author": "EminGT",
                "downloads": 51705265,
                "followers": 9704,
                "categories": [
                    "atmosphere",
                    "bloom",
                    "cartoon",
                    "colored-lighting",
                    "fantasy",
                    "foliage",
                    "high",
                    "iris",
                    "low",
                    "medium",
                    "optifine",
                    "pbr",
                    "potato",
                    "reflections",
                    "shadows",
                    "vanilla-like"
                ],
                "project_type": "shader",
                "latest_game_version": "yCCduG44"
            },
            {
                "slug": "complementary-unbound",
                "title": "Complementary Shaders - Unbound",
                "author": "EminGT",
                "downloads": 33224978,
                "followers": 5205,
                "categories": [
                    "atmosphere",
                    "bloom",
                    "cartoon",
                    "colored-lighting",
            
…(truncated, see openapi.json for full schema)
```

### Versions

#### `GET /v1/versions` — A project's recent releases

**Parameters:**
- `slug` (query, required, string) — Project slug Example: `sodium`
- `limit` (query, optional, string) — Max versions (1-50) Example: `15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/versions?slug=sodium&limit=15"
```

**Response:**
```json
{
    "data": {
        "slug": "sodium",
        "count": 15,
        "source": "Modrinth",
        "versions": [
            {
                "name": "Sodium 0.9.0-beta.2 for Fabric 26.2-rc-1",
                "loaders": [
                    "fabric"
                ],
                "featured": false,
                "downloads": 64,
                "version_type": "beta",
                "game_versions": [
                    "26.2-rc-1"
                ],
                "date_published": "2026-06-12T00:47:33.259264Z",
                "version_number": "mc26.2-rc-1-0.9.0-beta.2-fabric"
            },
            {
                "name": "Sodium 0.9.0-beta.1 for Fabric 26.2-rc-1",
                "loaders": [
                    "fabric"
                ],
                "featured": false,
                "downloads": 285,
                "version_type": "beta",
                "game_versions": [
                    "26.2-rc-1"
                ],
                "date_published": "2026-06-11T21:42:56.402555Z",
                "version_number": "mc26.2-rc-1-0.9.0-beta.1-fabric"
            },
            {
                "name": "Sodium 0.8.12-alpha.4 for Fabric 1.21.1",
                "loaders": [
                    "fabric"
                ],
                "featured": false,
                "downloads": 244756,
                "version_type": "alpha",
                "game_versions": [
                    "1.21.1"
                ],
                "date_publis
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Look up a project by its slug (slug=sodium, iris, fabric-api). search accepts type=mod|modpack|shader|resourcepack|datapack and sort=downloads|follows|newest|updated|relevance. Downloads is the headline popularity metric.",
        "source": "Modrinth public API (api.modrinth.com/v2, live)",
        "service": "modrinth-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/search": "Search projects (q=shaders, type=shader, sort=downloads).",
            "GET /v1/project": "A project in full — downloads, followers, type, loaders (slug=sodium).",
            "GET /v1/versions": "A project's recent releases with per-version downloads (slug=sodium)."
        },
        "description": "Live mod-platform stats from Modrinth, the open Minecraft content platform. The adoption-and-community view of the Minecraft modding ecosystem — how much each mod, modpack, shader or resource pack is downloaded and followed, and which projects are most popular. project = a single project in full (downloads, followers, type, categories, supported game versions and loaders, sides, license); search = search projects filterable by type and sortable by downloads or follows; versions = a project's recent releases with per-version downloads, game versions and loaders. Live, no key, nothing stored. Distinct from the other developer-ecosystem and gaming APIs.",
        "upstream_status": "ok",
        "sodium_downloads": 166010755
…(truncated, see openapi.json for full schema)
```

### Projects

#### `GET /v1/dependencies` — The projects a project depends on

**Parameters:**
- `slug` (query, required, string) — Project slug Example: `sodium`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/dependencies?slug=sodium"
```

**Response:**
```json
{
    "data": {
        "slug": "sodium",
        "count": 2,
        "source": "Modrinth",
        "dependencies": [
            {
                "slug": "canvas",
                "title": "Canvas Renderer",
                "downloads": 60193,
                "project_type": "mod"
            },
            {
                "slug": "notenoughcrashes",
                "title": "Not Enough Crashes",
                "downloads": 11404971,
                "project_type": "mod"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-13T13:54:18.227Z",
        "request_id": "d542d0fc-0c81-4147-879d-8bf09169c0b8"
    },
    "status": "ok",
    "message": "Dependencies retrieved successfully",
    "success": true
}
```

#### `GET /v1/members` — The team behind a project

**Parameters:**
- `slug` (query, required, string) — Project slug Example: `sodium`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/members?slug=sodium"
```

**Response:**
```json
{
    "data": {
        "slug": "sodium",
        "count": 3,
        "source": "Modrinth",
        "members": [
            {
                "name": null,
                "role": "Maintainer",
                "avatar": "https://avatars3.githubusercontent.com/u/31803019?v=4",
                "user_id": "DzLrfrbK",
                "username": "IMS"
            },
            {
                "name": null,
                "role": "Project Lead",
                "avatar": "https://cdn.modrinth.com/user/TEZXhE2U/f4705a5f2388c65029ae2e59f1434b3e6e4de23a.png",
                "user_id": "TEZXhE2U",
                "username": "jellysquid3"
            },
            {
                "name": null,
                "role": "Maintainer",
                "avatar": "https://avatars.githubusercontent.com/u/17120022?v=4",
                "user_id": "PSleyMoH",
                "username": "douira"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-13T13:54:18.540Z",
        "request_id": "c9af746b-b731-4b94-8410-0372f232ab73"
    },
    "status": "ok",
    "message": "Members retrieved successfully",
    "success": true
}
```

### Creators

#### `GET /v1/user` — A creator's profile and their projects

**Parameters:**
- `username` (query, required, string) — Modrinth username Example: `jellysquid3`
- `limit` (query, optional, string) — Max projects (1-50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/modrinth-api/v1/user?username=jellysquid3&limit=20"
```

**Response:**
```json
{
    "data": {
        "id": "TEZXhE2U",
        "bio": "Professional idiot at day, maniac programmer by night.",
        "url": "https://modrinth.com/user/jellysquid3",
        "name": null,
        "avatar": "https://cdn.modrinth.com/user/TEZXhE2U/f4705a5f2388c65029ae2e59f1434b3e6e4de23a.png",
        "joined": "2021-01-03T00:49:18.373336Z",
        "source": "Modrinth",
        "projects": [
            {
                "slug": "sodium",
                "title": "Sodium",
                "downloads": 166791786,
                "followers": 37273,
                "project_type": "mod"
            },
            {
                "slug": "lithium",
                "title": "Lithium",
                "downloads": 98782569,
                "followers": 21770,
                "project_type": "mod"
            },
            {
                "slug": "phosphor",
                "title": "Phosphor",
                "downloads": 820117,
                "followers": 2878,
                "project_type": "mod"
            },
            {
                "slug": "hydrogen",
                "title": "Hydrogen",
                "downloads": 420867,
                "followers": 1014,
                "project_type": "mod"
            }
        ],
        "username": "jellysquid3",
        "project_count": 4,
        "total_downloads": 266815339
    },
    "meta": {
        "timestamp": "2026-06-13T13:54:18.900Z",
        "request_id": "06886065-e865-41ce-9e33-fb2bba2d2720"
    },
    
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/modrinth-api
OpenAPI spec: https://www.oanor.com/api/modrinth-api/openapi.json