Projects API

API endpoints for managing Modrinth projects (mods, modpacks, resource packs, etc.)

Get Project

Retrieve a single project by its ID or slug.

GET /v3/project/{id}

Path Parameters

id · string · required

The project ID or slug

Response

id · string

The project’s unique ID

slug · string

The project’s URL-safe slug

name · string

The project’s name

summary · string

A short summary of the project

description · string

The full project description

categories · array

List of category names (max 3)

additional_categories · array

List of additional category names (max 256)

license · object

The project’s license information

Show properties

id · string

SPDX license identifier

url · string

URL to the license text

status · string

Project status: approved, rejected, draft, unlisted, archived, processing, withheld, scheduled, private, unknown

downloads · integer

Total download count

followers · integer

Number of followers

published · string

ISO 8601 timestamp of when the project was first published

updated · string

ISO 8601 timestamp of when the project was last updated

team_id · string

The ID of the project’s team

Example Request

curl https://api.modrinth.com/v3/project/sodium

Example Response

{
  "id": "AANobbMI",
  "slug": "sodium",
  "name": "Sodium",
  "summary": "A modern rendering engine for Minecraft",
  "description": "Sodium is a free and open-source mod...",
  "categories": ["optimization", "fabric"],
  "additional_categories": [],
  "license": {
    "id": "LGPL-3.0-only",
    "url": "https://cdn.modrinth.com/licenses/lgpl-3.txt"
  },
  "status": "approved",
  "downloads": 50000000,
  "followers": 25000,
  "published": "2020-07-07T00:00:00Z",
  "updated": "2024-01-15T10:30:00Z",
  "team_id": "3vHspAEn"
}

---

Get Multiple Projects

Retrieve multiple projects by their IDs or slugs.

GET /v3/projects?ids=["id1","id2"]

Query Parameters

ids · string · required

JSON array of project IDs or slugs as a string

Example Request

curl 'https://api.modrinth.com/v3/projects?ids=["sodium","lithium"]'

---

Check Project ID

Check if a project ID or slug exists and get its canonical ID.

GET /v3/project/{id}/check

Path Parameters

id · string · required

The project ID or slug to check

Response

id · string

The canonical project ID if it exists

Example Request

curl https://api.modrinth.com/v3/project/sodium/check

---

Search Projects

Search for projects with filters.

GET /v3/search

Query Parameters

query · string

The search query

facets · string

Facets to filter by (JSON string)

index · string

The sorting method: relevance, downloads, follows, newest, updated

offset · integer

The offset for pagination (default: 0)

limit · integer

Number of results to return (default: 10, max: 100)

Example Request

curl 'https://api.modrinth.com/v3/search?query=optimization&facets=[["categories:fabric"]]&limit=20'

---

Get Random Projects

Get a random selection of projects.

GET /v3/projects_random?count=10

Query Parameters

count · integer · required

Number of random projects to return (min: 1, max: 100)

Example Request

curl 'https://api.modrinth.com/v3/projects_random?count=5'

---

Update Project

Update a project’s metadata. Requires authentication and PROJECT_WRITE scope.

PATCH /v3/project/{id}

Path Parameters

id · string · required

The project ID or slug

Request Body

name · string

New project name (3-64 characters)

summary · string

New project summary (3-256 characters)

description · string

New project description (max 65536 characters)

categories · array

New categories array (max 3)

additional_categories · array

New additional categories (max 256)

license_id · string

SPDX license identifier

license_url · string

URL to license text (max 2048 characters)

slug · string

New URL-safe slug (3-64 characters)

status · string

New project status

link_urls · object

Object mapping platform names to URLs (or null to delete)

Example Request

curl -X PATCH https://api.modrinth.com/v3/project/sodium \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "An updated summary",
    "categories": ["optimization", "fabric", "performance"]
  }'

---

Bulk Edit Projects

Edit multiple projects at once. Requires authentication.

PATCH /v3/projects?ids=["id1","id2"]

Query Parameters

ids · string · required

JSON array of project IDs

Request Body

categories · array

Set categories for all projects

add_categories · array

Add categories to all projects

remove_categories · array

Remove categories from all projects

additional_categories · array

Set additional categories

add_additional_categories · array

Add additional categories

remove_additional_categories · array

Remove additional categories

link_urls · object

Update link URLs for all projects

---

Delete Project

Delete a project. Requires authentication and appropriate permissions.

DELETE /v3/project/{id}

Path Parameters

id · string · required

The project ID or slug

Example Request

curl -X DELETE https://api.modrinth.com/v3/project/my-project \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Follow/Unfollow Project

Follow or unfollow a project. Requires authentication.

POST /v3/project/{id}/follow
DELETE /v3/project/{id}/follow

Path Parameters

id · string · required

The project ID or slug

Example Request

# Follow a project
curl -X POST https://api.modrinth.com/v3/project/sodium/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

# Unfollow a project
curl -X DELETE https://api.modrinth.com/v3/project/sodium/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Get Project Dependencies

Get all dependencies for a project.

GET /v3/project/{project_id}/dependencies

Path Parameters

project_id · string · required

The project ID or slug

Response

projects · array

Array of dependent projects

versions · array

Array of specific dependent versions

Example Request

curl https://api.modrinth.com/v3/project/iris/dependencies

---

Manage Project Icon

Upload or delete a project icon. Requires authentication.

PATCH /v3/project/{id}/icon?ext=png
DELETE /v3/project/{id}/icon

Path Parameters

id · string · required

The project ID or slug

Query Parameters (PATCH only)

ext · string · required

Image file extension (png, jpg, etc.)

Example Request

# Upload icon
curl -X PATCH 'https://api.modrinth.com/v3/project/sodium/icon?ext=png' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary '@icon.png'

# Delete icon
curl -X DELETE https://api.modrinth.com/v3/project/sodium/icon \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Manage Gallery Images

Add, edit, or delete gallery images. Requires authentication.

POST /v3/project/{id}/gallery?ext=png&featured=true
PATCH /v3/project/{id}/gallery?url=...&title=...&description=...
DELETE /v3/project/{id}/gallery?url=...

Common Use Cases

Creating a New Project

1. Prepare project metadata
2. Create the project via API or web interface
3. Upload initial version with files
4. Set project icon and gallery images
5. Submit for approval if needed

Managing Project Visibility

• Use status field to control project visibility
• approved - Public and searchable
• unlisted - Public but not in search
• private - Only visible to team members
• draft - Not yet published

Working with Categories

• Main categories (max 3) are used for primary classification
• Additional categories (max 256) for more specific tags
• Categories must exist in the platform’s category list