Mod portal API

Category: Internal API

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}

To get even more information about a mod, you can use the following URL.

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

Endpoints

/api/mods

GET Parameters (sent as query parameters):

Key	Values	Description
hide_deprecated	{boolean}	Only return non-deprecated mods.
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 or 'max'}	The amount of results to show in your search
sort	{enum, one of name, created_at or updated_at}	Sort results by this property. Defaults to name when not defined. Ignored for page_size=max queries.
sort_order	{enum, one of asc or desc}	Sort results ascending or descending. Defaults to descending when not defined. Ignored for page_size=max queries.
namelist	{array of strings}	Return only mods that match the given names. Either comma-separated names or supply the namelist parameter more than once. Response will include releases instead of latest_release.
version	{enum, one of 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 1.0, 1.1 or 2.0}	Only return non-deprecated mods compatible with this Factorio version

Returns #Mod List Response

/api/mods/{mod_name}

Return short information of a specific mod.

See #Result Entry, "Short" column.

/api/mods/{mod_name}/full

Returns more information of a mod.

See #Result Entry, "Full" column.

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 "api/mods endpoint" column, those returned by the api/mods/{name} endpoint are marked with a check in the "Short" column and those returned by the api/mods/{name}/full endpoint are marked in the "Full" column. Fields may be absent if there is no data.

Key	Type	api/mods endpoint	Short	Full	Description
latest_release	Release?	✓			The latest version of the mod available for download. Absent when the namelist parameter is used.
downloads_count	Integer	✓	✓	✓	Number of downloads.
name	String	✓	✓	✓	The mod's machine-readable ID string.
owner	String	✓	✓	✓	The Factorio username of the mod's author.
releases	Release[]	✓*	✓	✓	A list of different versions of the mod available for download. See #Releases. *Only when using namelist parameter.
summary	String	✓	✓	✓	A shorter mod description.
title	String	✓	✓	✓	The mod's human-readable name.
category	Category?	✓	✓	✓	A single category describing the mod. See Mod_details_API#Category.
score	Integer	✓	✓*	✓*	The score of the mod. *Only when not 0.
thumbnail	String(relative URL)		✓	✓	The relative path to the thumbnail of the mod. For mods that have no thumbnail it may be absent or default to "/assets/.thumb.png". Prepend "assets-mod.factorio.com".
changelog	String			✓	A string describing the recent changes to a mod.
created_at	String(ISO 8601)			✓	ISO 8601 for when the mod was created.
description	String			✓	A longer description of the mod, in text only format.
source_url	String			✓	A URL to the mod's source code.
github_path	String			✓	Deprecated: Use source_url instead. 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.
tags	Tag[]			✓	A list of tag names that categorize the mod. See #Tags.
license	#License[]			✓	The license that applies to the mod. See #License.
deprecated	Boolean?			✓	<ref></ref>True if the mod is marked as deprecated by its owner. Absent when false.

Releases

Only difference here between the api/mods/{name} endpoint and the api/mods/{name}/full endpoint is that the full one includes an array of dependencies in the info_json object.

Key	Type	Description
download_url	String	Path to download for a mod. starts with "/download" and does not include a full url. See #Downloading Mods
file_name	String	The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
info_json	Object	A copy of the mod's info.json file, only contains factorio_version in short version, also contains an array of dependencies in full version
released_at	String(ISO 8601)	ISO 8601 for when the mod was released.
version	String	The version string of this mod release. Used to determine dependencies.
sha1	String	The sha1 key for the file

Tags

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

id	type	name	title	description
12	t	transportation	Transportation	Transportation of the player, be it vehicles or teleporters.
13	t	logistics	Logistics	Augmented or new ways of transporting materials - belts, inserters, pipes!
??	t	combat	Combat	New ways to deal with enemies, be it attack or defense.
17	t	enemies	Enemies	Changes to enemies or entirely new enemies to deal with.
18	t	armor	Armor	Armors or armor equipment.
??	t	environment	Environment	Map generation and terrain modification.
20	t	logistic-network	Logistics Network	Related to roboports and logistic robots
??	t	circuit-network	Circuit network	Entities which interact with the circuit network.
21	t	storage	Storage	More than just chests.
22	t	power	Power Production	Changes to power production and distribution.
23	t	manufacturing	Manufacture	Furnaces, assembling machines, production chains
24	t	blueprints	Blueprints	Change blueprint behavior.
25	t	cheats	Cheats	Play it your way.
27	t	mining	Mining	New ores and resources as well as machines.
??	t	fluids	Fluids	Things related to oil and other fluids.
29	t	trains	Trains	Trains are great, but what if they could do even more?

License

Key	Type	Description
description	String	A short description of the license.
id	String	The unique id of the license.
name	String	The internal name of the license.
title	String	The human-readable title of the license.
url	String	Usually a URL to the full license text, but can be any string.

Error

Key	Type	Description
message	String

Downloading Mods

You can get the full url by appending the download_url to mods.factorio.com, but if you're not authenticated, you will be redirected to mods.factorio.com/login. Logging in to that would give you access to the file. Fortunately, there's a better way to do this. Simply adding username and token parameters to the download url will prevent the redirecting and let you download the file immediately. The token can be acquired from a json file called "player-data.json", located in the User Data directory (see Application_directory#User_data_directory). You can also get the token by using the Web Authentication API.

Example usage: https://mods.factorio.com/{download_url}?username={username}&token={token}