canonical: https://jentic.com/apis/modrinth.com/modrinth # Modrinth API Modrinth publishes its own OpenAPI specification for Modrinth API in its developer documentation. Modrinth is an open-source platform for hosting and distributing Minecraft mods, modpacks, resource packs, shaders, and plugins. The API allows searching the project catalogue, fetching project and version metadata, downloading mod files, and managing user followed projects through a personal access token. ## For AI agents Search and download Minecraft mods, modpacks, resource packs, and shaders, and manage user follows through Modrinth's open mod catalogue. ## Scope Does not host non-Minecraft games, manage in-game purchases, or run Minecraft servers - use for Modrinth project search and download only. ## Capabilities - Search the Modrinth catalogue for mods filtered by Minecraft version, loader, and category - Retrieve project metadata including title, description, license, and download counts - List and download specific versions of a mod or modpack - Look up the latest version compatible with a given Minecraft version and Fabric or Forge loader - Manage the authenticated user's followed projects and notifications ## Use cases ### Modpack Launcher Mod Search Power the search and install flow inside a third-party Minecraft launcher with the Modrinth catalogue. The launcher queries Modrinth for projects matching the player's Minecraft version and loader, lets the player pick a version, and downloads the mod jar straight from Modrinth's CDN. Most launchers wire this up in under a week because the API is well documented and rate limits are generous. Example prompt: Search Modrinth for projects matching 'sodium' compatible with Minecraft 1.20.1 and the Fabric loader, then return the latest version's primary download URL ### Server-Side Mod Update Bot Run a scheduled bot that checks each mod installed on a Minecraft server for newer Modrinth versions, downloads the update, and posts a Discord summary. The bot uses project version listings to detect updates and the file manifest to verify SHA-512 checksums before swapping jars on disk. Example prompt: For every mod jar in the server's mods folder, query Modrinth for newer versions on Minecraft 1.20.1 Forge and download any updates ### Agent-Driven Modpack Curation via Jentic Use a Jentic-connected agent to curate themed modpacks by querying Modrinth for top projects in a category, fetching their licences and dependency lists, and assembling a manifest. The agent searches Jentic for the operation, loads the schema, and walks the catalogue without a developer hand-rolling each request. Example prompt: Build a 'magic and exploration' modpack manifest by selecting the top 15 Modrinth projects in those categories that share a permissive licence and target Minecraft 1.20.1 ## Key resources - **Projects** — Search and retrieve mods, modpacks, resource packs, shaders, and plugins - **Versions** — List, retrieve, and download specific versions of a project - **Users** — Look up user profiles and manage followed projects ## Why Jentic - **Setup:** Wiring the Modrinth API by hand means handling its bearer auth, mapping project slugs and version ids into each call, and coding search and download-URL retrieval yourself. Through Jentic you install once, import the Modrinth API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Modrinth addresses projects and versions by id in the URL path, so a rule can pin your agent to one project: it can search Modrinth and read that project's versions and download URLs. You choose the operations it may call, so managing a user's followed projects and notifications is not included unless you add it. - **Credential handling:** Your Modrinth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'search Modrinth for Fabric mods for Minecraft 1.20.1' or 'get a project version's download URL', and Jentic returns the matching Modrinth operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **CurseForge API** — CurseForge is the largest commercial Minecraft modding platform with a similar mod-and-modpack catalogue. - **mod.io API** — mod.io hosts user-generated mods across many games with cross-platform console support. - **Steam Web API** — Steam Web API verifies game ownership and reads Workshop subscriptions for the Steam version of Minecraft-adjacent titles. ## FAQ ### Which OpenAPI specification does this Modrinth API page describe? Modrinth's own OpenAPI document, published at https://docs.modrinth.com/openapi.yaml: an OpenAPI 3.0.0 file titled Labrinth (version v2.7.0/366f528) covering 55 paths of the v2 API as Modrinth documents it. Jentic does not publish a separate specification for the Modrinth API. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Modrinth API use? Read endpoints such as project search and version listing are public and require no auth. User-scoped endpoints - managing follows, notifications, or uploading new versions - require a personal access token issued from the Modrinth account settings, sent as a Bearer token in the Authorization header. Through Jentic the token stays in the encrypted Jentic One instance. ### Can I download a mod jar directly through the API? Yes. After resolving a project's version, the version response includes a files array with direct download URLs to Modrinth's CDN plus SHA-1 and SHA-512 hashes for integrity verification. Agents should download via the file URL rather than constructing one manually. ### What are the rate limits for the Modrinth API? Modrinth applies a default rate limit of 300 requests per minute per IP for unauthenticated traffic, with authenticated tokens generally treated more leniently. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers - agents should back off on 429. ### How do I search for Minecraft mods through Jentic? Run pip install jentic, then search Jentic for 'find Minecraft mods on Modrinth'. Jentic returns the project search operation with its query schema, including filters for game versions, loaders, and categories. Load the schema, pass the filters, and execute. ### Is the Modrinth API free to use? Yes. Modrinth is an open-source, donation-funded platform and the API is free for both creators and downstream tools, subject to the published rate limits and the platform's terms of use. ### Can I limit what my agent is allowed to do with the Modrinth API? Yes. Because you run Jentic One yourself, your own rules decide which Modrinth operations and credentials the agent may use. Since Modrinth addresses projects and versions by id in the URL path, you can pin the agent to a single project so it only searches the catalogue and reads that project's versions and download URLs. You choose the operations it may call, so managing a user's followed projects and notifications stays off the table unless you explicitly add it.