Mod details API

Category: Public API

The mod details API is used to change mod information like the description on the Factorio mod portal. It requires an API key with the ModPortal: Edit Mods usage, which can be created on https://factorio.com/profile.

It accepts multipart/form-data HTTP requests and responds with JSON encoded objects.

Endpoint

edit_details

URL	https://mods.factorio.com/api/v2/mods/edit_details
HTTP Method	POST

HTTP Request Header

Authorization

Bearer $APIKey

Authorization header with the APIKey and a "Bearer " prefix -> "Bearer $APIKey"

HTTP Request Body

mod	string, mandatory	Internal name of the mod whose details are to be changed
title	string, optional	Display name of the mod. Min length 1, max length 250
summary	string, optional	Short description of the mod. Max length 500
description	string, optional	Long description of the mod in markdown format
category	enum, optional	Mod category, see #Category
tags	enum, optional, multiple possible	Mod tags, see #Tags
license	enum, optional	Mod license, see #License
homepage	string, optional	URL of mod homepage (URL must use http or https scheme). Max length 256
deprecated	bool, optional	Deprecated flag to hide mod from public listings
source_url	string, optional	URL of mod source code repository (URL must use http or https scheme)
faq	string, optional	FAQ for the mod in markdown format

JSON object response

success	bool	This attribute only appears for successful requests. It's set to true.
url	string	This attribute only appears for successful requests. URL path to get mod details endpoint
error	string	This attribute only appears on failed requests.
message	string	This attribute only appears on failed requests. Has details about the problem.

Possible API Error Responses

Possible values for the error property of API responses

InvalidApiKey	Missing or invalid API key for the current endpoint
InvalidRequest	Invalid request.
InternalError	Internal error, please try again later.
Forbidden	Insufficent permission for current endpoint
Unknown	Unknown error, please try again later.
UnknownMod	Mod does not exist in mod portal

Enums

Category

Value	Name	Description
<empty string>	No category
content	Content	Mods introducing new content into the game.
overhaul	Overhaul	Large total conversion mods.
tweaks	Tweaks	Small changes concerning balance, gameplay, or graphics.
utilities	Utilities	Providing the player with new tools or adjusting the game interface, without fundamentally changing gameplay.
scenarios	Scenarios	Scenarios, maps, and puzzles.
mod-packs	Mod packs	Collections of mods with tweaks to make them work together.
localizations	Localizations	Translations for other mods.
internal	Internal	Lua libraries for use by other mods and submods that are parts of a larger mod.

Tags

Value	Name	Description
transportation	Transportation	Transportation of the player, be it vehicles or teleporters.
logistics	Logistics	Augmented or new ways of transporting materials - belts, inserters, pipes!
trains	Trains	Trains are great, but what if they could do even more?
combat	Combat	New ways to deal with enemies, be it attack or defense.
armor	Armor	Armors or armor equipment.
enemies	Enemies	Changes to enemies or entirely new enemies to deal with.
environment	Environment	Map generation and terrain modification.
mining	Mining	New Ores and resources as well as machines.
fluids	Fluids	Things related to oil and other fluids.
logistic-network	Logistic network	Related to roboports and logistic robots.
circuit-network	Circuit network	Entities which interact with the circuit network.
manufacturing	Manufacturing	Furnaces, assembling machines, production chains.
power	Power	Changes to power production and distribution.
storage	Storage	More than just chests.
blueprints	Blueprints	Change blueprint behavior.
cheats	Cheats	Play it your way.

License

Value	Name	Description	URL
default_mit	MIT	A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.	https://opensource.org/licenses/MIT
default_gnugplv3	GNU GPLv3	The GNU GPL is the most widely used free software license and has a strong copyleft requirement. When distributing derived works, the source code of the work must be made available under the same license.	https://opensource.org/licenses/gpl-3.0
default_gnulgplv3	GNU LGPLv3	Version 3 of the GNU LGPL is an additional set of permissions to the GNU GPLv3 license that requires that derived works be licensed under the same license, but works that only link to it do not fall under this restriction.	https://opensource.org/licenses/lgpl-3.0
default_mozilla2	Mozilla Public License 2.0	The Mozilla Public License (MPL 2.0) is maintained by the Mozilla foundation. This license attempts to be a compromise between the permissive BSD license and the reciprocal GPL license.	https://opensource.org/licenses/mpl-2.0
default_apache2	Apache License 2.0	A permissive license that also provides an express grant of patent rights from contributors to users.	https://opensource.org/licenses/apache-2.0
default_unlicense	The Unlicense (Public Domain)	Because copyright is automatic in most countries, the Unlicense is a template to waive copyright interest in software you've written and dedicate it to the public domain. Use the Unlicense to opt out of copyright entirely. It also includes the no-warranty statement from the MIT/X11 license.	http://unlicense.org/
custom_$ID	Custom	Custom license. The ID can be taken from the edit URL on the "My licenses" page on the mod portal. mods.factorio.com/licenses/edit/$ID	https://mods.factorio.com/licenses

Python Example

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
EDIT_MOD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/edit_details"

apikey = getenv("MOD_EDIT_API_KEY")
modname = getenv("MOD_NAME")

request_body = data = {"mod": modname, "faq": "# hello world", tags=["power", "storage"], category="tweaks"}
request_headers = {"Authorization": f"Bearer {apikey}"}

response = requests.post(EDIT_MOD_URL, data=request_body, headers=request_headers)

if not response.ok:
    print(f"edit failed: {response.text}")
    sys.exit(1)

print(f"edit successful: {response.text}")