In other languages:

Mod details API

From Official Factorio Wiki
Revision as of 17:46, 7 December 2022 by Bilka (talk | contribs) (added info on restrictions for multiple properties in the body)
Jump to navigation Jump to search
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
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
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}")