View source for Mod upload API

<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Public|Public API]]</div>
The mod upload API is used to add new releases to mods on the Factorio mod portal. It requires an API key with the <code>ModPortal: Upload Mods</code> usage, which can be created on https://factorio.com/profile. 

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

It was first announced on the Factorio forums. [https://forums.factorio.com/viewtopic.php?f=189&t=101769&p=562619#p562619]

== Endpoints ==
=== init_upload ===
{| class="wikitable"
| URL || https://mods.factorio.com/api/v2/mods/releases/init_upload 
|-
| HTTP Method || <code>POST</code>
|}

HTTP Request Header
{| class="wikitable"
| Authorization|| <code>Bearer $APIKey</code> || Authorization header with the APIKey and a "Bearer " prefix -> "Bearer $APIKey"
|}

HTTP Request Body
{| class="wikitable"
| mod || string || Name of the mod, for which a new release will be uploaded
|}

JSON object response
{| class="wikitable"
| upload_url || string || URL the mod zip file should be uploaded to
|-
| error || string || This attribute only appears on <strong>failed</strong> requests.
|-
| message || string || This attribute only appears on <strong>failed</strong> requests. Has details about the problem.
|}

=== finish_upload ===
{| class="wikitable"
| URL || <code>$upload_url</code> URL returned by the init_upload endpoint
|-
| HTTP Method || <code>POST</code> 
|-
|}

HTTP Request Body
{| class="wikitable"
| file || Mod zip file
|}

JSON object response
{| class="wikitable"
| success || bool || This attribute only appears on <strong>successful</strong> uploads. It's set to true.
|-
| error || string || This attribute only appears on <strong>failed</strong> uploads.
|-
| message || string || This attribute only appears on <strong>failed</strong> uploads. Has details about the problem.
|}

== Possible API Error Responses ==
Possible values for the <code>error</code> property of API responses
{| class="wikitable"
| 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
|-
| UnknownMod || Mod does not exist in mod portal
|}

== Python Example ==
<syntaxhighlight lang="python">
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/releases/init_upload"

apikey = getenv("MOD_UPLOAD_API_KEY")
modname = getenv("MOD_UPLOAD_NAME")
zipfilepath = getenv("MOD_UPLOAD_FILE")

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(zipfilepath, "rb") as f:	
	request_body = {"file": 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}")
</syntaxhighlight>

[[Category:Technical]]