Creating Projects

Learn how to create and publish your first project on Modrinth

This guide walks you through creating a new project on Modrinth, from setting up basic information to uploading your first version.

Project Creation Overview

When you create a project on Modrinth, you’ll need to provide essential metadata, upload project files, and configure settings. Projects can be created as mods, modpacks, resource packs, shaders, plugins, or data packs.

Prerequisites

• A Modrinth account with PROJECT_CREATE permissions
• At least one version file ready to upload
• Project icon (recommended, 256KB max, PNG/JPEG format)

You must have at least one initial version when submitting a project for review. Draft projects can be created without versions.

Required Project Information

Initial Versions

You must include at least one version when creating a project for review. See Managing Versions for detailed information about version requirements.

initial_versions · array · required

Versions to create with your project (1-32 versions)

Each version requires:

• Version number
• Version title
• File uploads
• Supported loaders (e.g., Fabric, Forge)
• Loader-specific fields (game versions, etc.)
• Release channel (release, beta, alpha)

Project Status

is_draft · boolean

Create as a draft project

• true - Save as draft without submitting for review
• false - Submit for moderation review (default)

Draft projects:

• Not visible to the public
• Can be edited freely
• Must have at least one version to submit for review

requested_status · string

Desired status after approval

Options:

• approved - Listed and searchable (default)
• unlisted - Accessible via direct link only
• private - Only visible to team members

Organization Projects

organization_id · string

Create project under an organization

Requirements:

• You must be a member of the organization
• You need ADD_PROJECT organization permission
• Project owner will be the organization, not you

API Example

Here’s a complete example of creating a project via the API:

curl -X POST https://api.modrinth.com/v3/project \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'data={
    "name": "My Awesome Mod",
    "slug": "awesome-mod",
    "summary": "A mod that makes Minecraft more awesome",
    "description": "# My Awesome Mod\n\nThis mod adds amazing features...",
    "categories": ["technology", "utility"],
    "license_id": "MIT",
    "initial_versions": [{
      "version_number": "1.0.0",
      "version_title": "Initial Release",
      "version_body": "First release of the mod",
      "file_parts": ["file"],
      "loaders": [{"0": "fabric"}],
      "fields": {
        "game_versions": ["1.20.1", "1.20.2"]
      },
      "release_channel": "release",
      "featured": true,
      "dependencies": []
    }],
    "is_draft": false,
    "requested_status": "approved"
  }' \
  -F 'icon=@icon.png' \
  -F 'file=@mod-1.0.0.jar'

Project Limits

Users have a maximum project limit based on their account standing. If you’ve reached your limit, you’ll receive a limit_reached error.

To check your current usage:

GET /v3/user/{id}/projects

Validation and Errors

Common errors when creating projects:

• Slug collision - The slug is already taken or conflicts with a project ID
• Invalid category - Category doesn’t exist or doesn’t match project type
• Invalid loader - Loader not supported by Modrinth
• Invalid game version - Game version not recognized
• Missing required fields - Name, slug, summary, description, or license not provided
• File validation failed - Uploaded files don’t pass security/format checks
• Duplicate files - File hash already exists in another project

After Creation

Once your project is created:

1. Processing - Your project enters moderation queue
2. Automated checks - Files are scanned for security issues
3. Manual review - Moderators review your project (if needed)
4. Approval - Project becomes visible at your requested status

Most projects are approved within 24-48 hours. You’ll receive notifications about your project’s status.

Next Steps

• Managing Versions - Upload updates and new versions
• Teams and Permissions - Add collaborators
• Analytics - Track your project’s performance