Download mod.io and unleash your creativity with cross-platform mod support for games
Welcome to the official documentation for mod.io, an API for developers to add mod support to their games. We recommend you read our Getting Started guide below to accurately and efficiently consume our REST API.
download mod.io
Once you have added your game to mod.io and got your game ID and API key, you can start integrating the mod.io REST API into your game, tools and sites. There are 3 options to get connected which you can use interchangeably depending on your needs. Here's the breakdown of each option.
At the moment it is not possible to open the mod.io website in-game with the user pre-authenticated, however you can provide a hint by appending ?portal=PORTAL to the end of the URL. What this tells mod.io, is that when the user attempts to perform an action that requires authentication, they will be prompted to login with their PORTAL account. For example if you want to take a mod creator to their mod webpage in-game on Steam, the URL would look something like: =steam. You can optionally add &login=auto as well to automatically start the login process. Supported portals can be found here.
mod.io allows you to specify the permission each access token has (default is read+write), this is done by the use of scopes. See below for a full list of scopes available, you must include at least one scope when generating a new token.
By default, all access token's are long-lived - meaning they are valid for a common year (not leap year) from the date of issue. You should architect your application to smoothly handle the event in which a token expires or is revoked by the user themselves or a mod.io admin, triggering a 401 Unauthorized API response.
If an error occurs, mod.io returns an error object with the HTTP code, error_ref and message to describe what happened and when possible how to avoid repeating the error. It's important to know that if you encounter errors that are not server errors (500+ codes) - you should review the error message before continuing to send requests to the endpoint.
When requests contain invalid input data or query parameters (for filtering), an optional field object called errors can be supplied inside the error object, which contains a list of the invalid inputs. The nested errors object is only supplied with 422 Unprocessable Entity responses. Be sure to review the Response Codes to be aware of the HTTP codes that the mod.io API returns.
Along with generic HTTP response codes, we also provide mod.io specific error codes to help you better understand what has gone wrong with a request. Below is a list of the most common error_ref codes you could encounter when consuming the API, as well as the reason for the error occuring. For error codes specific to each endpoint, click the 'Show All Responses' dropdown on the specified endpoint documentation.
How to download mod.io for PC
Download mod.io SDK for Unity
Download mod.io plugin for Unreal Engine
Download mod.io games with cross-platform mod support
Download mod.io app for Android
Download mod.io app for iOS
Download mod.io app for Xbox
Download mod.io app for PlayStation
Download mod.io app for Nintendo Switch
Download mod.io app for Oculus Quest
Download mod.io app for SteamVR
Download mod.io API documentation
Download mod.io source code from GitHub
Download mod.io UGC toolkit for game developers
Download mod.io white-label customization options
Download mod.io analytics and insights dashboard
Download mod.io moderation toolset
Download mod.io community guidelines
Download mod.io case studies and testimonials
Download mod.io logo and branding assets
Best games to download from mod.io
How to download mods from mod.io
How to upload mods to mod.io
How to manage mods with mod.io
How to integrate mods with mod.io
How to run events and contests with mod.io
How to showcase top creators with mod.io
How to grow your player-base with mod.io
How to increase retention with mod.io
How to deepen the relationship with your fans with mod.io
How to discover new long-tail keywords with mod.io
How to optimize your game for SEO with mod.io
How to rank higher on Google with mod.io
How to drive more traffic to your game with mod.io
How to monetize your game with mod.io
How to get started with mod.io in 3 easy steps
How to request a demo of mod.io features and benefits
How to contact the mod.io team for support and feedback
How to join the mod.io community on Discord and Twitter
How to subscribe to the mod.io newsletter and blog updates
What is the difference between mod.io and other UGC platforms?
What are the advantages of using mod.io over Steam Workshop?
What are the challenges of implementing cross-platform mod support?
What are the best practices for creating and curating UGC?
What are the latest trends and innovations in UGC?
What are some examples of successful games using mod.io?
What are some tips and tricks for using mod.io effectively?
What are some common questions and answers about mod.io?
What are some reviews and ratings of mod.io by users and developers?
What are some future plans and roadmap of mod.io?
mod.io has powerful filtering available to assist you when making requests to the API. You can filter on all columns in the parent object only. You cannot apply filters to columns in nested objects, so if a game contains a tags object you cannot filter by the tag name column, but you can filter by the games name since the games name resides in the parent object.
The mod.io API provides localization for a collection of languages. To specify responses from the API to be in a particular language, simply provide the Accept-Language header with an ISO 639 compliant language code. If a valid language code is not provided and the user is authenticated, the language they have selected in their profile will be used. All other requests will default to English (US). The list of supported codes includes:
To help familiarize yourself with the mod.io API and to ensure your implementation is battle-hardened and operating as intended, we have setup a test sandbox which is identical to the production environment. The test sandbox allows you to make requests to the API whilst your integration is a work in progress and the submitted data is not important. When you are ready to go live it's as easy as adding your game to the production environment, substituting the test API URL for the production API URL, and updating the api_key and game_id you are using to the values from your games profile on production.
If you are a large studio or publisher and require a private, in-house, custom solution that accelerates your time to market with a best-in-class product, reach out to developers@mod.io to discuss the licensing options available.
If you spot any errors within the mod.io documentation, have feedback on how we can make it easier to follow or simply want to discuss how awesome mods are, feel free to reach out to developers@mod.io or come join us in our discord channel. We are here to help you grow and maximise the potential of mods in your game.
mod.io supports mods on all platforms. Games can enable per-platform mod file support in their dashboard, if they wish to control which platforms each mod and their corresponding files can be accessed on. Otherwise, all mods and their files will be available on all platforms the game supports. To make this system work, it's important the following headers are included in all API requests as explained below. If you have any questions about setting up cross-platform mod support in your game, please reach out to developers@mod.io.
When making API requests you should include the X-Modio-Platform header (with one of the values below), to tell mod.io what Platform the request is originating from. This header is important because it enables mod.io to return data that is approved for the platform such as:
Official mod.io Plugins and SDKs will automatically supply this value for you providing you have specified the correct platform in the tools' settings. We strongly recommend you supply this header in every request with the correct platform to enable mod.io to provide the best cross-platform experience for your players. Please see a list of supported platforms below:
When making API requests you should include the X-Modio-Portal header (with one of the values below), to tell mod.io what Portal (eg. Store or App) the request is originating from. This header is important because it enables mod.io to fine-tune the experience, such as returning display names used by players on that portal (which can be a certification requirement).
We use mod.io to support user-generated content in-game. By clicking 'I Agree' you agree to the mod.io Terms of Use and a mod.io account will be created for you (using your display name, avatar and ID). Please see the mod.io Privacy Policy on how mod.io processes your personal data. I Agree No, ThanksTerms of Use - Privacy Policy
IMPORTANT: It is a requirement of the Game Terms with mod.io, and the platforms mod.io is used on, to ensure the user provides consent and has agreed to the latest mod.io Terms of Use and Privacy Policy. The users agreement must be collected prior to using a 3rd party authentication flow (including but not limited to Steam, PSN, Nintendo and Xbox Live). You only need to collect the users agreement once, and also each time these policies are updated.
NOTE: You can use your own text and process, but be aware that you are responsible for ensuring that the users agreement is properly collected and reported. Failure to do so correctly is a breach of the mod.io Game Terms. If your game does not authenticate users or only uses the email authentication flow, you do not need to implement this dialog, but you should link to the mod.io Terms of Use and Privacy Policy in your Privacy Policy/EULA.
Request an access token on behalf of a Steam user. To use this functionality you must add your games encrypted app ticket key from Steamworks, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.
HINT: If you want to overlay the mod.io site in-game on Steam, we recommend you add ?portal=steam to the end of the URL you open which will prompt the user to login with Steam. See Web Overlay Authentication for details.
HINT: If you want to overlay the mod.io site in-game on Xbox, we recommend you add ?portal=xboxlive to the end of the URL you open which will prompt the user to login with Xbox Live. See Web Overlay Authentication for details.
HINT: If you want to overlay the mod.io site in-game on PlayStation, we recommend you add ?portal=psn to the end of the URL you open which will prompt the user to login with PlayStation Network. See Web Overlay Authentication for details.
Request an access token on behalf of an Meta Quest user. To use this functionality you must add your games AppId and secret from the Meta Quest Dashboard, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.
Request an access token on behalf of a GOG Galaxy user. To use this functionality you must add your games encrypted app ticket key from GOG Galaxy, to the Game Admin > Settings page of your games profile on mod.io. A Successful request will return an Access Token Object.
HINT: If you want to overlay the mod.io site in-game on itch.io, we recommend you add ?portal=itchio to the end of the URL you open which will prompt the user to login with itch.io. See Web Overlay Authentication for details.
HINT: If you want to overlay the mod.io site in-game on Android, we recommend you add ?portal=google to the end of the URL you open which will prompt the user to login with Google. See Web Overlay Authentication for details.
HINT: If you want to overlay the mod.io site in-game with Discord authentication, we recommend you add ?portal=discord to the end of the URL you open which will prompt the user to login with Discord. See Web Overlay Authentication for details.
HINT: If you want to overlay the mod.io site in-game with your SSO, we recommend you add ?portal=openid to the end of the URL you open which will prompt the user to login with your identity provider. See Web Overlay Authentication for details.