> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/modrinth/code/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Introduction to the Modrinth API and its core concepts

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:

<CodeGroup>
  ```bash Production theme={null}
  https://api.modrinth.com
  ```

  ```bash Staging theme={null}
  https://staging-api.modrinth.com
  ```
</CodeGroup>

<Note>
  Use the staging environment for testing and development. Switch to the production environment when your application is ready for production use.
</Note>

## Testing Your Connection

You can verify your API connection by making a GET request to the root endpoint:

```bash theme={null}
curl https://api.modrinth.com/
```

**Response:**

```json theme={null}
{
  "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`

<Warning>
  When an API version is deprecated, it will return a **410 Gone** status. Ensure your application handles these errors gracefully.
</Warning>

### 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`

<Note>
  While slugs and usernames can change, base62 IDs are permanent. Use IDs for long-term storage and references.
</Note>

### 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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl "https://api.modrinth.com/v2/search?index=downloads"
```

## User Agent Requirement

<Warning>
  You **must** provide a uniquely-identifying `User-Agent` header with all API requests. Requests with generic user agents may be blocked.
</Warning>

### 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 (contact@example.com)
```

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:

* **Swagger UI**: [https://api.modrinth.com/docs/swagger-ui](https://api.modrinth.com/docs/swagger-ui)
* **OpenAPI JSON**: [https://api.modrinth.com/docs/openapi.json](https://api.modrinth.com/docs/openapi.json)
* **OpenAPI YAML**: [https://docs.modrinth.com/openapi.yaml](https://docs.modrinth.com/openapi.yaml)

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

```json theme={null}
{
  "id": "AABBCCDD",
  "name": "My Project",
  "slug": "my-project"
}
```

**201 Created** - Resource created

```json theme={null}
{
  "id": "IIJJKKLL",
  "name": "Version 1.0.0"
}
```

**204 No Content** - Request succeeded with no response body

### Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "error": "error_type",
  "description": "Human-readable error message"
}
```

See the [Errors](/api/errors) page for detailed information about error handling.

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate API requests with personal access tokens and OAuth
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Understand rate limiting and how to handle 429 responses
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api/errors">
    Learn about HTTP status codes and error response formats
  </Card>

  <Card title="Projects API" icon="book" href="/api/projects">
    Explore the projects and versions API endpoints
  </Card>
</CardGroup>