Mod publish API

Category: Experimental API

The mod publish API is used to add new mods to the Factorio mod portal. It requires an API key with the ModPortal: Publish Mods usage, which can be created on https://factorio.com/profile.

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

Endpoints

init_publish

URL	https://mods.factorio.com/api/experimental/mods/init_publish
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

Name of the mod that will be published.

JSON object response

upload_url	string	URL the mod zip file should be uploaded to
error	string	This attribute only appears on failed requests.
message	string	This attribute only appears on failed requests. Has details about the problem.

finish_upload

URL	$upload_url URL returned by the init_publish endpoint
HTTP Method	POST

HTTP Request Body

file	file	Mod zip file
description	string, optional	Mod description in markdown format
category	enum, optional	Mod category, See Mod details API#Category
license	enum, optional	Mod category, See Mod details API#License
source_url	url, optional	Url to mod source code repository

JSON object response

success	bool	This attribute only appears on successful uploads. 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 uploads.
message	string	This attribute only appears on failed uploads. 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.
InvalidModRelease	Invalid release data in info.json
InvalidModUpload	Invalid mod data in zipfile
ModAlreadyExists	Mod name already exists in mod portal

Python example

MOD_PORTAL_URL = "https://mods.factorio.com"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/experimental/mods/init_publish"

apikey = getenv("MOD_UPLOAD_API_KEY")
modname = sys.argv[1]
filepath = sys.argv[2]

request_body = data = {"mod": modname}
request_headers = {"Authorization": f"Bearer {apikey}"}

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

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

upload_url = response.json()["upload_url"]

with open(filepath, "rb") as f:
    request_body = {"file": f}
    response = requests.post(upload_url, files=request_body, data={"description": "# published via API"})

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

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