modio

README

go-modio

---

Client for the mod.io REST API v1: search, sorts, mod details, files, dependencies, per-user API hosts and MD5-checked file addresses. Package modio, module github.com/Rethunk-Tech/go-modio.

Reads mod.io through a user's own read-only token, with errors a caller can tell apart: bad token, rate limit, other status.

Quick start

go get github.com/Rethunk-Tech/go-modio

A worked example and the contracts: HUMANS.md.

Features

• Search a game's mods by text, tags and ids, sorted by popularity, downloads, rating, update or name.
• Mod details, files with MD5 digests, tags and the signed-in account.
• Dependencies, recursive on request.
• Per-user API host (u-{user-id}.modapi.io) and the platform header.

Documentation

Doc	Audience
HUMANS.md	Running and using the package
AGENTS.md	Internals, invariants, and why
CONTRIBUTING.md	Process — commits, tests, docs
SECURITY.md	Vulnerability disclosure
CHANGELOG.md	Release notes

License

MIT — see LICENSE. © 2026 Rethunk.Tech, LLC.

Documentation

Overview

Package modio is a client for the mod.io REST API v1, read-only: search, sorts, mod details, files with their MD5 digests, dependencies and tags, signed with a user's OAuth access token.

Index

• Constants
• Variables
• func Denied(err error) bool
• func UserURL(userID int) string
• type Client
  • func New(cfg Config) *Client
  • func (c *Client) Dependencies(ctx context.Context, gameID, modID int, recursive bool) ([]Mod, error)
  • func (c *Client) Files(ctx context.Context, gameID, modID int) ([]File, error)
  • func (c *Client) Me(ctx context.Context) (User, error)
  • func (c *Client) Mod(ctx context.Context, gameID, modID int) (Mod, error)
  • func (c *Client) Search(ctx context.Context, q SearchQuery) (ModList, error)
  • func (c *Client) Tags(ctx context.Context, gameID int) ([]string, error)
• type Config
• type File
  • func (f File) Downloadable() bool
  • func (f File) MD5() string
  • func (f File) VersionName() string
• type Mod
  • func (m Mod) Explicit() bool
• type ModList
• type SearchQuery
• type User

Constants

const (
	// BaseURL is the API root for calls that need no per-user host.
	BaseURL = "https://api.mod.io/v1"
	// MaxPageSize is the API's largest _limit.
	MaxPageSize = 100
)

const (
	SortPopular   = "-popular"
	SortDownloads = "-downloads_total"
	SortRating    = "-rating"
	SortUpdated   = "-date_updated"
	SortNewest    = "-date_live"
	SortName      = "name"
)

Sort is a value for SearchQuery.Sort; a leading minus sorts descending.

const MaturityExplicit = 8

MaturityExplicit is the Mod.MaturityOption bit for explicit content.

Variables

var (
	// ErrNoToken means the Client has no access token; nothing is sent.
	ErrNoToken = errors.New("modio: no access token")
	// ErrNoFile means a mod has no downloadable file.
	ErrNoFile = errors.New("modio: mod has no file to download")
)

Functions

func Denied

func Denied(err error) bool

Denied reports an answer of 401, which means the token is mistyped, revoked or expired; tokens do not refresh.

func UserURL

func UserURL(userID int) string

UserURL is the API root mod.io assigns to a user's OAuth access token: u-{user-id}.modapi.io.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the mod.io API. It holds no state beyond its configuration, so it is safe for concurrent use and cheap to build again when the token changes.

func New

func New(cfg Config) *Client

New builds a Client.

func (*Client) Dependencies

func (c *Client) Dependencies(ctx context.Context, gameID, modID int, recursive bool) ([]Mod, error)

Dependencies lists the mods a mod depends on, all levels down when recursive. Creators also list soft credit links here, so a caller offers them and installs none unasked.

func (*Client) Files

func (c *Client) Files(ctx context.Context, gameID, modID int) ([]File, error)

Files lists a mod's files, newest first.

func (*Client) Me

func (c *Client) Me(ctx context.Context) (User, error)

Me reads the token's account.

func (*Client) Mod

func (c *Client) Mod(ctx context.Context, gameID, modID int) (Mod, error)

Mod reads one mod with its current file.

func (*Client) Search

func (c *Client) Search(ctx context.Context, q SearchQuery) (ModList, error)

Search lists a game's live mods.

func (*Client) Tags

func (c *Client) Tags(ctx context.Context, gameID int) ([]string, error)

Tags lists the names of a game's visible tags.

type Config

type Config struct {
	// Token is a read-only OAuth access token, sent as a bearer token. Empty makes every call fail with ErrNoToken.
	Token string
	// UserID, when set, sends calls to the token's own host (UserURL) instead of BaseURL.
	UserID int
	// Platform is sent as X-Modio-Platform ("windows", "linux", ...) and picks which build of a mod's files the API
	// returns; empty sends none.
	Platform string
	// HTTP sends every request; nil means http.DefaultClient. Redirects to another origin are refused so the token
	// stays with the API.
	HTTP *http.Client
	// BaseURL replaces the API root; it wins over UserID.
	BaseURL string
	// UserAgent is sent with every request when set.
	UserAgent string
}

Config is what a Client is built from.

type File

type File struct {
	ID        int    `json:"id"`
	Filesize  int64  `json:"filesize"`
	Filename  string `json:"filename"`
	Version   string `json:"version"`
	Changelog string `json:"changelog"`
	Filehash  struct {
		MD5 string `json:"md5"`
	} `json:"filehash"`
	Download struct {
		// BinaryURL can expire: read the file again right before downloading.
		BinaryURL string `json:"binary_url"`
	} `json:"download"`
}

File is one uploaded build of a mod.

func (File) Downloadable

func (f File) Downloadable() bool

Downloadable reports whether the file carries an address.

func (File) MD5

func (f File) MD5() string

MD5 is the lowercase hex digest the API publishes, its only hash.

func (File) VersionName

func (f File) VersionName() string

VersionName is the file's own version, or its id when the author left it blank.

type Mod

type Mod struct {
	ID             int    `json:"id"`
	Name           string `json:"name"`
	Summary        string `json:"summary"`
	Description    string `json:"description"`
	ProfileURL     string `json:"profile_url"`
	DateUpdated    int64  `json:"date_updated"`
	MaturityOption int    `json:"maturity_option"`
	SubmittedBy    struct {
		Username string `json:"username"`
	} `json:"submitted_by"`
	Logo struct {
		Thumb string `json:"thumb_320x180"`
	} `json:"logo"`
	Stats struct {
		Downloads       int `json:"downloads_total"`
		RatingsPositive int `json:"ratings_positive"`
	} `json:"stats"`
	Tags []struct {
		Name string `json:"name"`
	} `json:"tags"`
	// Modfile is the current file.
	Modfile File `json:"modfile"`
}

Mod is one mod listing.

func (Mod) Explicit

func (m Mod) Explicit() bool

Explicit reports the mod's maturity option includes explicit content.

type ModList

type ModList struct {
	Data  []Mod `json:"data"`
	Total int   `json:"result_total"`
}

ModList is one page of mods.

type SearchQuery

type SearchQuery struct {
	GameID int
	// Text matches names and summaries.
	Text string
	// Sort is one of the Sort constants; empty keeps the API's order.
	Sort string
	// TagsIn keeps mods carrying any listed tag; TagsNotIn drops mods carrying any.
	TagsIn, TagsNotIn []string
	// IDs keeps only these mods.
	IDs []int
	// Offset is the first mod's position and Limit the page length, at most MaxPageSize; zero Limit is MaxPageSize.
	Offset, Limit int
}

SearchQuery is one mods listing. Zero fields are not sent.

type User

type User struct {
	ID       int    `json:"id"`
	Username string `json:"username"`
}

User is the account a token belongs to.