canonical: https://jentic.com/apis/mod.io/mod-io-main

# mod.io API

mod.io is a cross-platform user-generated-content service for game developers, providing mod hosting, security scanning, content moderation, and SDK integration so player-made mods can be discovered and installed inside games on PC and consoles. The API exposes 27 endpoints under https://api.mod.io/v1 covering authentication, games, mods, files, comments, users, and subscriptions, plus platform-specific external auth flows for Steam, Xbox, PSN, Switch, and Oculus. Authentication supports an api_key query parameter for read-only access and OAuth 2.0 for user-context operations.

## For AI agents

Browse and manage mods, files, comments, and subscriptions on mod.io across 27 endpoints, with platform-specific auth for Steam, Xbox, PSN, Switch, and Oculus.

## Scope

Does not handle game distribution, payment processing, or matchmaking - use for mod hosting, moderation, and platform-bound mod authentication only.

## Capabilities

- Authenticate players via Steam, Xbox, PSN, Switch, or Oculus through the /external/* endpoints
- Browse the catalogue of supported games and their attached mods via /games and `/games/{game_id}/mods`
- Retrieve a specific mod's metadata and downloadable files
- Manage user subscriptions to mods so installs stay in sync across devices
- Read and post comments on a mod for community moderation
- Accept the mod.io terms of service through `/authenticate/terms` before user-context calls

## Use cases

### In-game mod browser

Game studios call `/games/{game_id}/mods` to render an in-game mod browser tailored to the title, then drill into `/games/{game_id}/mods/{mod_id}` for the detail view and file downloads. The catalogue is filtered server-side by game ID so each title sees only its own mods, and pagination keeps the in-game UI responsive.

Example prompt: GET `/games/{game_id}/mods` with sort='-popular' and pagesize=20, render the results in the in-game UI, then GET `/games/{game_id}/mods/{mod_id}` when the user opens a mod detail page.

### Cross-platform player authentication

When a player launches a game, the title exchanges the platform identity token for a mod.io session via the relevant /external endpoint - `/external/steamauth` on Steam, `/external/xboxauth` on Xbox, `/external/psnauth` on PSN, `/external/switchauth` on Switch, or `/external/oculusauth` on Meta Quest. The pattern lets the studio offer a single mod experience across consoles without managing platform credentials directly.

Example prompt: Submit the Steam ticket to `/external/steamauth`, capture the returned mod.io OAuth token, and use it to call `/authenticate/terms` for the player.

### Mod subscription and content moderation

Players subscribe to mods so the game client keeps installs current, while community moderators read and act on /comments to keep a mod's discussion healthy. Together the subscription and comment endpoints let a studio offer the full UGC loop - discover, install, discuss, moderate - without building it from scratch.

Example prompt: POST a subscription on the user's behalf for mod_id 99 in game_id 7, then GET `/games/7/mods/99/comments` for moderation review.

### Agent integration via Jentic

An AI assistant for a studio's community team can search Jentic for 'list mods for a mod.io game', load the `/games/{game_id}/mods` schema, and execute the call without exposing the api_key or OAuth token. The agent can then chain into mod detail and comments endpoints to summarise top community feedback.

Example prompt: Search Jentic for 'list mods for a mod.io game', load the `/games/{game_id}/mods` schema, execute it for game_id 7, and summarise the top 10 mods by recent activity.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/authenticate/terms` | Accept the mod.io terms of service |
| POST | `/external/steamauth` | Authenticate a Steam player |
| POST | `/external/xboxauth` | Authenticate an Xbox player |
| POST | `/external/psnauth` | Authenticate a PSN player |
| GET | `/games` | List games on mod.io |
| GET | `/games/{game_id}` | Get a specific game |
| GET | `/games/{game_id}/mods` | List mods for a game |
| GET | `/games/{game_id}/mods/{mod_id}` | Get a specific mod |

## Key resources

- **Authentication** — Accept terms and run platform-specific external auth flows
- **Games** — Browse the catalogue of games registered on mod.io
- **Mods** — List, retrieve, and manage mods attached to a game
- **Files** — Access downloadable files attached to a mod
- **Comments** — Read and post comments on a mod
- **User** — Manage user-context data for the authenticated player
- **Subscriptions** — Subscribe and unsubscribe a user to mods

## Why Jentic

- **Setup:** Wiring the mod.io API by hand means choosing between its api_key query auth and OAuth2, running the platform sign-in flows for Steam, Xbox, or PSN, and mapping game and mod ids yourself. Through Jentic you install once, import the mod.io API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** mod.io puts the game and mod ids in the URL path (`/games/{game_id}/mods/{mod_id}`), so a rule can pin your agent to one game's mods: it can list games and read that game's mods. You choose the operations it may call, so moderation and platform authentication are not included unless you add them.
- **Credential handling:** Your mod.io credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list mods for a game on mod.io' or 'get a mod's details', and Jentic returns the matching mod.io operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Steam Web API** — Steam platform API used to obtain the ticket consumed by `/external/steamauth`
- **Twitch Helix API** — Streamer and viewer data that pairs with in-game UGC discovery
- **GitHub REST API** — Source-control hosting sometimes used as an ad-hoc mod distribution channel

## FAQ

### What authentication does the mod.io API use?

Read-only calls accept an api_key query parameter, while user-context calls use OAuth 2.0 obtained from the /external/* platform auth endpoints (Steam, Xbox, PSN, Switch, Oculus). Through Jentic the api_key and OAuth tokens are stored in your Jentic One instance and injected automatically.

### Can I authenticate a Steam player against mod.io?

Yes. POST the Steam ticket to `/external/steamauth` and mod.io returns an OAuth token tied to the player's mod.io identity. Equivalent endpoints exist at `/external/xboxauth`, `/external/psnauth`, `/external/switchauth`, and `/external/oculusauth` for the other platforms.

### What are the rate limits for the mod.io API?

mod.io publishes a per-API-key rate limit on its developer documentation rather than in the OpenAPI specification. Treat HTTP 429 as the back-off signal and consult docs.mod.io for the current limit by tier.

### How do I list mods for a game through Jentic?

Run pip install jentic, search Jentic for 'list mods for a mod.io game', load the `/games/{game_id}/mods` schema, and execute it with the game_id. Jentic injects the api_key automatically and returns the paginated mod list.

### Can I subscribe a user to a mod via the API?

Yes. With a valid OAuth token from one of the /external auth flows you can call the subscription endpoints to subscribe and unsubscribe the user from specific mods, which keeps installs synchronised across the player's devices.

### Is the mod.io API free to use?

mod.io offers a free tier for indie developers with paid plans for higher-volume titles and console support. Confirm current pricing on mod.io. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the mod.io API?

Yes. Because Jentic One is self-hosted, you write the rules that decide which mod.io operations and credentials your agent may use. Since mod.io puts the game and mod ids in the URL path (`/games/{game_id}/mods/{mod_id}`), you can pin the agent to a single game so it only lists games and reads that game's mods. Operations like posting comments for moderation or the platform authentication flows for Steam, Xbox, PSN, Switch, and Oculus stay off unless you explicitly grant them.