Skip to main content
The Modrinth API (Labrinth) is a RESTful API that provides programmatic access to Modrinth’s platform for mods, modpacks, plugins, and resource packs.

​
Base URLs

Modrinth provides two API environments: 
https://api.modrinth.com
Use the staging environment for testing and development. Switch to the production environment when your application is ready for production use.

​
Testing Your Connection

You can verify your API connection by making a GET request to the root endpoint: 
curl https://api.modrinth.com/
Response: 
{
  "name": "modrinth-labrinth",
  "version": "2.7.0",
  "documentation": "https://docs.modrinth.com",
  "about": "Welcome traveler!"
}

​
API Versioning

Modrinth follows a simple versioning pattern with version numbers in the URL path:
  • v2: Current stable version - https://api.modrinth.com/v2
  • v3: Latest version - https://api.modrinth.com/v3
When an API version is deprecated, it will return a 410 Gone status. Ensure your application handles these errors gracefully.

​
Version Migration

When a new major version is released:
  1. The previous version is immediately considered deprecated
  2. No new features will be added to deprecated versions
  3. Deprecated versions will be maintained for a limited time
  4. Eventually, deprecated versions return a permanent 410 error

​
Data Format

All API endpoints return JSON-formatted responses with Content-Type: application/json.

​
Identifiers

Modrinth uses consistent identifier formats across the API:

​
Base62 IDs

Most resources use unique 8-digit base62 identifiers:
  • Projects: AABBCCDD
  • Versions: IIJJKKLL
  • Users: EEFFGGHH
  • Teams: MMNNOOPP
  • Reports: RRSSTTUU

​
Slugs and Usernames

Projects and users also have human-readable identifiers:
  • Project slugs: sodium, fabric-api
  • Usernames: my_username
While slugs and usernames can change, base62 IDs are permanent. Use IDs for long-term storage and references.

​
File Hashes

Version files are identified by SHA-1 or SHA-512 hashes: 
sha1: 619e250c133106bacc3e3b560839bd4b324dfda8
sha512: a1b2c3d4e5f6...

​
Pagination

Endpoints that return multiple items support pagination using offset/limit parameters: 
curl "https://api.modrinth.com/v2/search?limit=20&offset=0"
Parameters:
  • limit: Number of results per page (default: 10, max: 100)
  • offset: Number of results to skip

​
Filtering and Sorting

​
Search Facets

Many endpoints support filtering via facets: 
curl "https://api.modrinth.com/v2/search?facets=[[\"categories:fabric\"],[\"versions:1.20.1\"]]"
Common facets include:
  • categories: Filter by category (e.g., “technology”, “magic”)
  • versions: Filter by game version (e.g., “1.20.1”)
  • project_type: Filter by type (“mod”, “modpack”, “resourcepack”)
  • loaders: Filter by mod loader (“fabric”, “forge”, “quilt”)

​
Sorting

Search results can be sorted using the index parameter:
  • relevance: Most relevant (default)
  • downloads: Most downloads
  • follows: Most follows
  • newest: Newest first
  • updated: Recently updated
curl "https://api.modrinth.com/v2/search?index=downloads"

​
User Agent Requirement

You must provide a uniquely-identifying User-Agent header with all API requests. Requests with generic user agents may be blocked.

​
User Agent Format

Bad: 
User-Agent: okhttp/4.9.3
Good: 
User-Agent: my_project_name
Better: 
User-Agent: github_username/project_name/1.56.0
Best (with contact info): 
User-Agent: github_username/project_name/1.56.0 ([email protected])
Including contact information allows Modrinth to reach out about API usage issues before blocking traffic.

​
CORS Support

The Modrinth API supports Cross-Origin Resource Sharing (CORS) with a wildcard same-origin policy: 
Access-Control-Allow-Origin: *
This allows browser-based applications to make direct API requests without proxy servers.

​
OpenAPI Specification

A complete OpenAPI 3.0 specification is available: The specification can be imported into tools like Postman, Insomnia, or used to generate client SDKs.

​
Common Response Patterns

​
Success Responses

200 OK - Request succeeded 
{
  "id": "AABBCCDD",
  "name": "My Project",
  "slug": "my-project"
}
201 Created - Resource created 
{
  "id": "IIJJKKLL",
  "name": "Version 1.0.0"
}
204 No Content - Request succeeded with no response body

​
Error Responses

All errors follow a consistent format: 
{
  "error": "error_type",
  "description": "Human-readable error message"
}
See the Errors page for detailed information about error handling.

​
Next Steps

Authentication

Learn how to authenticate API requests with personal access tokens and OAuth

Rate Limits

Understand rate limiting and how to handle 429 responses

Error Handling

Learn about HTTP status codes and error response formats

Projects API

Explore the projects and versions API endpoints