Mod portal API

	This article is a stub, and not comprehensive.
	You can help this wiki by expanding it.

The Mod Portal API is used to both browse and download all mods available on the official Factorio mod portal. Using the API does not require any kind of authentication or account information and can be viewed simply by following the URLs below in any web browser.

https://mods.factorio.com/api/mods

More detailed information about a particular mod can be obtained by retrieving the following URL, where {name} is the mod's name field in the result object.

https://mods.factorio.com/api/mods/{name}

Endpoints

TODO!!!

/api/mods

GET Parameters:

Key	Values	Description
order	updated, alpha, top	How to order the mods, by most recently updated, alphabetically, or by most downloaded.
owner
page	{an integer}	Page number you would like to show. Makes it so you can see a certain part of the list without getting detail on all
page_size	{an integer}	The amount of results to show in your search
q	{a string}	Name/Partial Name of mod you want to search for
tags
namelist	{array of strings}	Return only mods that match the given names.

Returns #Mod List Response

/api/messages

GET Parameters:

Key	Values	Description
page_size	{an integer}	How many messages on one page
page	{an integer}	Which page of messages
mod	{name of mod}	Name of the specific mod that you want messages for
tag	{a letter}	The letter that represents the different message tags

JSON Object Types

Mod List Response

Key	Type	Description
pagination	Pagination	See #Pagination
results	Result[]	A list of mods, matching any filters you specified.

Pagination

Key	Type	Description
count	Integer	Total number of mods that match your specified filters.
links	Links	Utility links to mod portal api requests, preserving all filters and search queries.
page	Integer	The current page number.
page_count	Integer	The total number of pages returned.
page_size	Integer	The number of results per page.

Pagination Links

Key	Type	Description
first	String(URL)	URL to the first page of the results, or null if you're already on the first page.
prev	String(URL)	URL to the previous page of the results, or null if you're already on the first page.
next	String(URL)	URL to the next page of the results, or null if you're already on the last page.
last	String(URL)	URL to the last page of the results, or null if you're already on the last page.

Result Entry

Fields returned by the api/mods endpoint are marked with a check (✓) in the "Short" column, and those returned the the api/mods/{name} endpoint are marked with a check in the "Full" column.

Key	Type	Short	Full	Description
created_at	String(ISO 8601)	✓	✓	The datetime the mod was uploaded, in the full ISO 8601 format, with a space separator instead of 'T'.
current_user_rating	Null	✓	✓	Doesn't seem to be implemented yet. Always null.
description	String		✓	A longer description of the mod, in text only format.
description_html	String(HTML)		✓	A longer description of the mod, with HTML tags.
downloads_count	Integer	✓	✓	Number of downloads.
first_media_file	Media File	✓		The first media file in the "media_files" list.
game_versions	String[]	✓	✓	A list of major Factorio version strings (e.g. "0.13") starting with 0.13 that the mod is compatible with, in addition to the version(s) found in "latest_release" / "releases".
github_path	String	✓	✓	A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
homepage	String	✓	✓	Usually a URL to the mod's main project page, but can be any string.
id	Integer	✓	✓	A numerical mod ID used to identify the mod in other API endpoints.
latest_release	Release	✓		The latest version of the mod available for download. See #Releases
license_flags	Integer(11 bit)	✓	✓	A bit field describing what permissions the mod's license grants. See #License Flags
license_name	String	✓	✓	The mod's license name.
license_url	String	✓	✓	A URL link to the full license agreement. Can be any string in case of custom licenses.
media_files	Media File[]		✓	A list of media files, such as screen shots of the mod in action. See #Media Files.
name	String	✓	✓	The mod's machine-readable ID string.
owner	String	✓	✓	The Factorio username of the mod's author.
ratings_count	Integer	✓	✓	Doesn't seem to be implemented yet. Always 0.
releases	Release[]		✓	A list of different versions of the mod available for download. See #Releases
summary	String	✓	✓	A shorter mod description.
tags	Tag[]	✓	✓	A list of tag objects that categorize the mod. See #Tags.
title	String	✓	✓	The mod's human-readable name.
updated_at	String(ISO 8601)	✓	✓	The datetime the mod was last updated, in the full ISO 8601 format, with a space separator instead of 'T'.
visits_count	Integer	✓	✓	The number of times the mod was viewed, but perhaps only counted on the web interface???

License Flags

The "license_flags" is an 11 bit number that describe generally what permissions the mod's license grants.

2n	Title	Description
Permissions
0	Commercial Use	This software and derivatives may be used for commercial purposes
1	Modification	The software may be modified.
2	Distribution	You may distribute this software.
3	Patent Use	This license provides an express grant of patent rights from the contributor to the recipient.
4	Private Use	You may use and modify the software without distributing it.
Conditions
5	Disclose Source	Source code must be made available when distributing the software.
6	License & Copyright Notice	Include a copy of the license and copyright notice with the code.
7	Same License	Modifications must be released under the same license when distributing the software. In some cases a similar or related license may be used.
8	State Changes	Indicate changes made to the code.
Limitations
9	Hold Liable	Software is provided without warranty and the software author/license owner cannot be held liable for damages.
10	Trademark Use	This license explicitly states that it does NOT grant you trademark rights, even though licenses without such a statement probably do not grant you any implicit trademark rights.

Tags

Key	Type	Description
id	Integer	A numerical ID unique to this tag.
name	String	An all lower-case string used to identify this tag internally.
title	String	The tag's human-readable tag name.
description	String	A short description for the tag.
type	String

Currently, there are only a fixed number of tags available, these include:

id	type	name	title	description
1	t	general	General	Mods that cannot be sorted into other categories
2	t	non-game-changing	Non-Game-Changing	Changes only look&feel. New graphics, new sounds, ... such things.
3	t	helper-mods	Helper Mods	These mods are not game-changing, but enhance the gameplay by helping you with useful functions. Mods like showing the current game-time, keep track over your resources, rail-laying...
6	t	big-mods	Big Mods	Too big and/or changes too much of the game to be fit anywhere else
12	t	transportation	Transportation	Player transport
13	t	logistics	Logistics	Transport of materials
14	t	utility	Utility	Helps with certain things the player is doing.
15	t	balancing	Balancing	Makes the game much more fair
17	t	enemies	Enemies	Adds more enemies for more challange
16	t	weapons	Weapons	Adds more weapons to annihilate the enemy
18	t	armor	Armor	Armors or armor equipment related.
19	t	oil	Oil	Things related to oil related manufacture
20	t	logistics-network	Logistics Network	Related to roboports and logistic robots
21	t	storage	Storage	Allows more ways to be able to store items
22	t	power-production	Power Production	Allows more ways to create mass amounts of energy
23	t	manufacture	Manufacture	Furnaces, assembling machines, production chains
24	t	blueprints	Blueprints
25	t	cheats	Cheats	Well, they let you cheat
26	t	defense	Defense	Mods that add the ability to protect your base more
27	t	mining	Mining	Mods that provide better or new ways of mining resources
28	t	info	Info	Mods that provide additional information to the player
29	t	trains	Trains	Related to trains

Media Files

A media file object describes a single image, along with a smaller thumbnail sized version of the image.

Key	Type	Description
id	Integer	A numerical ID unique to this media file.
width	Integer	Width of the full sized image in pixels.
height	Integer	Height of the full sized image in pixels.
size	Integer	Size of the full image in bytes.
urls	Media URL	URLs to the full sized image and a thumbnail, see below.

Media URLs

Key	Type	Description
original	String(URL)	URL to full sized image.
thumb	String(URL)	URL to 128x128px sized thumbnail of image.

The original image is in either PNG, JPEG, or GIF formats, with the extensions ".png", ".jpg", or ".gif". All image URLs seem to be located at https://mods-data.factorio.com/pub_data/media_files/ with a file name consisting of 12 alphanumerical characters (of the base64 alphabet) followed by the file extension. The thumbnail URL contains the same code, but instead with a file extension of ".thumb.png".

Releases

Key	Type	Description
download_url	String	Path to download for a mod. starts with "/api" and does not include a full url
downloads_count	Integer	Count of how many times a mod has been downloaded
factorio_version	String	The version of the game the mod is intended for
file_name	String	The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
file_size	Integer	The size of the file
game_version	String	The version of the mod (do not confuse with factorio version)
id	Integer	A numerical ID unique to this release.
info_json	Object	A copy of the mod's info.json file.
released_at	String(ISO 8601)	ISO 6501 for when the mod was released.
version	String	The version string of this mod release. Used to determine dependencies.

Error

Key	Type	Description
detail	String