Mod images API

Category: Public API

The mod images API is used to add, reorder or remove mod images 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.

Endpoints

add

URL	https://mods.factorio.com/api/v2/mods/images/add
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, for which a new image will be uploaded

JSON object response

upload_url	string	URL the image 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 add endpoint
HTTP Method	POST

HTTP Request Body

image

Image file

JSON object response

id	string	This attribute only appears on successful uploads. SHA1 of the uploaded image.
url	bool	This attribute only appears on successful uploads. Url of the uploaded image.
thumbnail	bool	This attribute only appears on successful uploads. Url of thumbnail of the uploaded image.
error	string	This attribute only appears on failed uploads.
message	string	This attribute only appears on failed uploads. Has details about the problem.

edit

URL	https://mods.factorio.com/api/v2/mods/images/edit
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, for which a new image will be uploaded
images	string	List of comma-seperated image ids that should be displayed on the mod page

JSON object response

success	bool	This attribute only appears on successful uploads. It's set to true.
images	list	This attribute only appears on successful uploads. List of objects with id, url and thumbnail attribute same as finish_upload 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.
InvalidImageUpload	Invalid image file uploaded.
UnknownMod	Mod does not exist in mod portal

Python Examples

Add Image

import sys
import requests
from os import getenv

MOD_PORTAL_URL = "https://mods.factorio.com"
INIT_UPLOAD_URL = f"{MOD_PORTAL_URL}/api/v2/mods/images/add"

apikey = getenv("MOD_EDIT_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 = {"image": f}
    response = requests.post(upload_url, files=request_body)

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

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

Edit Images

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/images/edit"

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

image_ids = ["fdc375d5ca3c263fedafb7ef143c82f9fb668472", "47bda5cd27ef49fe86fe03f803cb5c351a848586"]
image_ids_text = ",".join(image_ids)

request_body = data = {"mod": modname, "images": image_ids_text}
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}")