Skip to main content

​
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
​
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"
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