Mod details API

Category: Experimental 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
summary	string, optional	Short description of the mod
description	string, optional	Long description of the mod in markdown format
category	enum, optional	Mod category, see #Category
license	enum, optional	Mod license, see #License
homepage	strong, optional	URL of mod homepage
deprecated	bool, optional	Deprecated flag to hide mod from public listings
source_url	strong, optional	URL of mod source code repository
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
general	General	Mods that cannot be sorted into other categories
non-game-changing	Non-Game-Changing	Changes only look&feel. New graphics, new sounds, etc.
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...
transportation	Transportation	Player transport
logistics	Logistics	Transport of materials
utility	Utility	Helps with certain things the player is doing.
balancing	Balancing
weapons	Weapons
enemies	Enemies
armor	Armor	Armors or armor equipment related.
oil	Oil	Things related to oil related manufacture
logistic-network	Logistic network	Related to roboports and logistic robots
circuit-network	Circuit network
storage	Storage
power-production	Power production
manufacture	Manufacture	Furnaces, assembling machines, production chains
blueprints	Blueprints
cheats	Cheats
defense	Defense
mining	Mining
environment	Environment
info	Info	Mods that provide additional information to the player
trains	Trains
big-mods	Big mods	Too big and/or changes too much of the game to be fit anywhere else
scenarios	Scenarios	Story mode campaigns on a premade map
mod-packs	Mod packs	Collections of mods with tweaks to make them work together!
libraries	Libraries	Mods used by other mods

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"}
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}")