DOCUMENTATION
Author operations
Upload files, update metadata and check status.
Access requirements#
| Requirement | Check |
|---|---|
| App | Explicit consent and required scopes: mods:create + files:upload for uploads, mods:update for metadata. |
| User | Delegated rh_user_, current mods.upload/other permission and existing author-eligibility checks. |
| Resource | Ownership, visibility, allowed fields and fresh checks before commit. |
| Key & plan | rh_live_ keys are read-only. Payment grants no write/upload authority, paid content or moderator privileges. |
What is excluded#
Write operations#
| Operation | Purpose |
|---|---|
| POST /mods; POST /uploads/external | Google Drive reference: name, category, googleDriveFileId and allowed metadata. Registers for moderation; not binary upload. |
| PATCH /mods/{id} | Own-mod metadata only: name/category/description/type/version/project, per schema and current rules. |
| GET /mods/{id}/upload-status | Delegated-owner status only; never exposes internal files/tokens. |
| POST /upload-sessions | Create a ZIP upload session; protocol and limits below. |
| GET/PATCH /upload-sessions/{id}; POST /upload-sessions/{id}/commit | Check status, send sequential file chunks and commit. The mod is free and pending moderation. |
ZIP upload · 15 minutes#
- POST /upload-sessions: JSON with name, category, filename, bytes and sha256 (64 lowercase hex characters). Optional description/type/version/project. filename is a ZIP basename, such as local.zip. Before .zip, use 1–91 ASCII letters, digits, hyphens or underscores; start with a letter or digit.
- The API envelope contains data.id (UUID), offset=0, sessionToken (shown once), expiresIn=900 and maxChunkBytes=1048576. Keep the sessionToken only in session memory.
- GET requires the same Bearer and X-Upload-Session. PATCH also requires Upload-Offset, Content-Type: application/octet-stream and exact Content-Length (1..1048576). The body is raw bytes. No TUS headers, compression or chunked transfer.
- The last PATCH stages a valid ZIP without publishing it. Send JSON {} to POST /upload-sessions/{id}/commit. Hash, length, archive, storage limits, consent and current permissions are rechecked. Result: committed with status=pending.
File safety & limits#
- 22 bytes..256 MiB per ZIP; chunks up to 1 MiB; 15-minute lifetime; one active public session per user across all grants/projects.
- Upload reservations are limited to 2 GiB globally and 1 GiB per user; the author storage limit also applies. Completed uploads and uploads with uncertain outcomes remain reserved. This is separate from billing-period request quota.
- Only ZIP is accepted: up to 10000 entries and 512 MiB declared uncompressed size. Encrypted entries, symlinks, nested archives and path traversal are rejected. These checks do not replace malware scanning or verify full decompression and every file CRC.
- The mod is created free, with zero price and pending moderation. Use only schema-defined fields; ownership, publisher, price and access gates cannot be changed.
If a write response is lost#
Local test upload examples#
Run these examples only in an isolated local test environment with a disposable ZIP and delegated test token. Scripts reject external hosts and read-only developer keys; explicit command-line flags are required to send requests. Secrets are neither printed nor persisted.
Local upload invocation
# Set REDUXHUB_TEST_TOKEN to your short-lived delegated local test token.
node local-examples/upload.mjs --allow-local-write --commit-local --target http://127.0.0.1:1335/public/v1 --file local.zip --name "Local sample" --category redux
python local-examples/upload.py --allow-local-write --commit-local --target http://127.0.0.1:1335/public/v1 --file local.zip --name "Local sample" --category redux
# curl script: additionally set REDUXHUB_LOCAL_API to that exact local base.
sh local-examples/upload.sh --allow-local-write local.zip redux "Local sample" --commit-local
# --check on Node/Python validates target without file, token or network.cURL · one ZIP ≤1 MiB
cURL · one ZIP ≤1 MiB
#!/bin/sh
# LOCAL disposable test ZIP only, one chunk <=1 MiB. Node/Python support larger files.
# Requires curl + Python 3 standard library; no jq/install. Never run with shell tracing.
set +x
set -eu
[ "${1-}" = '--allow-local-write' ] || { echo 'Explicit --allow-local-write required; no requests sent.' >&2; exit 1; }
[ "$#" -ge 4 ] || { echo 'Usage: upload.sh --allow-local-write local.zip TEST_CATEGORY "Local sample" [--commit-local]' >&2; exit 1; }
FILE=$2
CATEGORY=$3
NAME=$4
COMMIT=${5-}
: "${REDUXHUB_LOCAL_API:?Explicit local target required: http://127.0.0.1:PORT/public/v1}"
: "${REDUXHUB_TEST_TOKEN:?Ephemeral delegated LOCAL test token required, not a developer key}"
# All validation runs before curl. Refuse production, DNS hosts, proxies and placeholders.
META=$(python3 -c '
import hashlib,json,os,re,sys
from urllib.parse import urlsplit
base=os.environ["REDUXHUB_LOCAL_API"]
if not re.fullmatch(r"http://127\.0\.0\.1:[0-9]{1,5}/public/v1",base): raise SystemExit("Numeric loopback target required")
if not 1 <= urlsplit(base).port <= 65535: raise SystemExit("Invalid local port")
if not re.fullmatch(r"rh_user_[A-Za-z0-9_-]{43}",os.environ["REDUXHUB_TEST_TOKEN"]): raise SystemExit("Delegated LOCAL token required")
file,category,name=sys.argv[1:]
filename=os.path.basename(file)
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,90}\.zip",filename): raise SystemExit("Plain local.zip basename required")
size=os.path.getsize(file)
if not 22 <= size <= 1048576: raise SystemExit("This curl example requires 22 bytes through 1 MiB; use Node/Python for chunks")
with open(file,"rb") as source: sha=hashlib.sha256(source.read(1048577)).hexdigest()
print(json.dumps(dict(name=name,category=category,filename=filename,bytes=size,sha256=sha)))
' "$FILE" "$CATEGORY" "$NAME")
# Pass credentials to curl via stdin config, not shell history or files. No -L or retries.
CREATED=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions"
request = "POST"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "Content-Type: application/json"
data = "$(printf '%s' "$META" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read())[1:-1])')"
EOF
)
# stdout is captured in shell memory only; never echo the server response/session token.
ID=$(printf '%s' "$CREATED" | python3 -c 'import json,re,sys;d=json.load(sys.stdin)["data"];assert re.fullmatch(r"[a-f0-9-]{36}",d["id"]);assert d["offset"]==0;print(d["id"])')
SESSION=$(printf '%s' "$CREATED" | python3 -c 'import json,re,sys;t=json.load(sys.stdin)["data"]["sessionToken"];assert re.fullmatch(r"rh_upload_[A-Za-z0-9_-]{43}",t);print(t)')
BYTES=$(printf '%s' "$META" | python3 -c 'import json,sys;print(json.load(sys.stdin)["bytes"])')
STATUS=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
EOF
)
printf '%s' "$STATUS" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="uploading" and d["offset"]==0'
# --data-binary reads only the selected local file. No compression/TUS/chunked transfer.
APPENDED=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --data-binary "@$FILE" --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID"
request = "PATCH"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
header = "Upload-Offset: 0"
header = "Content-Type: application/octet-stream"
header = "Content-Length: $BYTES"
EOF
)
printf '%s' "$APPENDED" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="staged" and d["offset"]==int(sys.argv[1])' "$BYTES"
if [ "$COMMIT" = '--commit-local' ]; then
RESULT=$(curl --silent --show-error --fail --max-time 15 --max-redirs 0 --noproxy '*' --proto '=http' --config - <<EOF
url = "$REDUXHUB_LOCAL_API/upload-sessions/$ID/commit"
request = "POST"
header = "Authorization: Bearer $REDUXHUB_TEST_TOKEN"
header = "X-Upload-Session: $SESSION"
header = "Content-Type: application/json"
data = "{}"
EOF
)
printf '%s' "$RESULT" | python3 -c 'import json,sys;d=json.load(sys.stdin)["data"];assert d["state"]=="committed" and d["status"]=="pending";print("Local test upload pending moderation; not published")'
else
echo 'Staged only. Reservation remains until known cleanup or an explicit local commit.'
fi
# On any uncertain PATCH/commit, STOP. Query authoritative status with SAME credentials.
# Never replay blindly; unknown/committing states require operator investigation.
unset CREATED SESSION STATUS APPENDED RESULT REDUXHUB_TEST_TOKEN
Node.js · chunks ≤1 MiB
Node.js · chunks ≤1 MiB
/** Explicitly opted-in LOCAL test writes only. No browser code or private signing key. */
import { request as httpRequest } from 'node:http';
import { open } from 'node:fs/promises';
import { basename, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { createHash } from 'node:crypto';
export const MAX_FILE = 256 * 1024 * 1024;
export const CHUNK = 1024 * 1024;
export function localTarget(raw) {
if (!/^http:\/\/127\.0\.0\.1:[0-9]{1,5}\/public\/v1$/.test(raw || '')) throw new Error('Explicit numeric loopback --target http://127.0.0.1:PORT/public/v1 required');
const url = new URL(raw);
if (!url.port || Number(url.port) > 65535 || Number(url.port) < 1) throw new Error('An explicit non-default local port is required');
return url;
}
export function delegatedToken(value) {
if (!/^rh_user_[A-Za-z0-9_-]{43}$/.test(value || '')) throw new Error('Set REDUXHUB_TEST_TOKEN to an ephemeral delegated LOCAL test token, never a developer key');
return value;
}
export function parseOptions(argv) {
const options = {};
for (let i = 0; i < argv.length; i++) {
const key = argv[i];
if (['--allow-local-write', '--commit-local', '--check'].includes(key)) options[key.slice(2)] = true;
else if (['--target', '--file', '--name', '--category'].includes(key) && argv[i + 1] && !argv[i + 1].startsWith('--')) options[key.slice(2)] = argv[++i];
else throw new Error('Unknown/missing argument. Use --check --target URL or explicit --allow-local-write --target URL --file local.zip --name NAME --category CATEGORY [--commit-local]');
}
localTarget(options.target);
return options;
}
function transport(target, token) {
return (method, path, body, session, offset) => new Promise((accept, reject) => {
const headers = { Authorization: 'Bearer ' + token, Accept: 'application/json' };
if (session) headers['X-Upload-Session'] = session;
if (body) { headers['Content-Type'] = Buffer.isBuffer(body) ? 'application/octet-stream' : 'application/json'; headers['Content-Length'] = String(Buffer.byteLength(Buffer.isBuffer(body) ? body : JSON.stringify(body))); }
if (offset !== undefined) headers['Upload-Offset'] = String(offset);
// Numeric loopback, no DNS/proxy environment, redirect following or retry.
const req = httpRequest({ hostname: '127.0.0.1', port: Number(target.port), path: '/public/v1' + path, method, headers, agent: false }, res => {
const chunks = []; let total = 0;
res.on('data', chunk => { total += chunk.length; if (total > 65536) req.destroy(new Error('Bounded response exceeded')); else chunks.push(chunk); });
res.on('end', () => {
if (res.statusCode < 200 || res.statusCode >= 300) { reject(new Error('Local API HTTP ' + res.statusCode + '; stop and inspect session status. No automatic retry.')); return; }
try { const value = JSON.parse(Buffer.concat(chunks).toString('utf8')); if (value.success !== true || !value.data || typeof value.data !== 'object') throw new Error(); accept(value.data); }
catch { reject(new Error('Invalid local API envelope; stop, do not replay a write')); }
});
res.on('error', reject);
});
req.setTimeout(15000, () => req.destroy(new Error('Local request deadline; outcome may be ambiguous. Query status before any manual recovery.')));
req.on('error', () => reject(new Error('Local request failed; outcome may be ambiguous. Do not replay PATCH/commit. Query status with the same credentials.')));
if (body) req.write(Buffer.isBuffer(body) ? body : JSON.stringify(body));
req.end();
});
}
export async function upload(options, env = process.env, requestOverride) {
const target = localTarget(options.target);
if (options.check) return { checked: true, network: false };
if (!options['allow-local-write']) throw new Error('--allow-local-write is mandatory; no request was sent');
const token = delegatedToken(env.REDUXHUB_TEST_TOKEN);
if (!options.file || !options.name || !options.category) throw new Error('--file, --name and --category must identify disposable LOCAL test data');
const filename = basename(options.file);
if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,90}\.zip$/.test(filename)) throw new Error('Use a plain ASCII local.zip basename');
const file = await open(resolve(options.file), 'r');
try {
const info = await file.stat();
if (!info.isFile() || info.size < 22 || info.size > MAX_FILE) throw new Error('ZIP must be 22 bytes through 256 MiB');
const buffer = Buffer.alloc(CHUNK), hash = createHash('sha256');
for (let offset = 0; offset < info.size;) { const { bytesRead } = await file.read(buffer, 0, Math.min(CHUNK, info.size - offset), offset); if (!bytesRead) throw new Error('Local file changed'); hash.update(buffer.subarray(0, bytesRead)); offset += bytesRead; }
const call = requestOverride || transport(target, token);
const created = await call('POST', '/upload-sessions', { name: options.name, category: options.category, filename, bytes: info.size, sha256: hash.digest('hex') });
if (!/^[a-f0-9-]{36}$/.test(created.id || '') || !/^rh_upload_[A-Za-z0-9_-]{43}$/.test(created.sessionToken || '') || created.offset !== 0 || created.maxChunkBytes !== CHUNK) throw new Error('Invalid session response; stop without retry');
const path = '/upload-sessions/' + created.id, secret = created.sessionToken;
let offset = 0, state = created.state;
while (offset < info.size) {
const status = await call('GET', path, undefined, secret);
if (status.offset !== offset || status.state !== 'uploading') throw new Error('Unexpected authoritative offset/state; no automatic resume');
const { bytesRead } = await file.read(buffer, 0, Math.min(CHUNK, info.size - offset), offset);
if (!bytesRead) throw new Error('Local file changed');
const appended = await call('PATCH', path, Buffer.from(buffer.subarray(0, bytesRead)), secret, offset);
if (appended.offset !== offset + bytesRead) throw new Error('Ambiguous append offset; stop without retry');
offset = appended.offset; state = appended.state;
}
if (state !== 'staged') throw new Error('Final chunk was not staged; do not commit');
if (!options['commit-local']) return { state: 'staged', note: 'Reserved until known cleanup or explicit local commit; not published' };
const result = await call('POST', path + '/commit', {}, secret);
if (result.state !== 'committed' || result.status !== 'pending') throw new Error('Ambiguous commit; stop without replay');
return { state: 'committed', status: 'pending' };
} finally { await file.close(); }
}
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
try { const result = await upload(parseOptions(process.argv.slice(2))); console.log(JSON.stringify(result)); }
catch (error) { console.error(error.message); process.exitCode = 1; }
}
Python · standard library
Python · standard library
"""Opted-in LOCAL ZIP test writes only. Python standard library; no signing keys."""
import argparse
import hashlib
import http.client
import json
import os
from pathlib import Path
import re
from urllib.parse import urlsplit
CHUNK = 1024 * 1024
MAX_FILE = 256 * 1024 * 1024
def local_target(raw):
if not re.fullmatch(r"http://127\.0\.0\.1:[0-9]{1,5}/public/v1", raw or ""):
raise ValueError("Explicit numeric loopback --target http://127.0.0.1:PORT/public/v1 required")
target = urlsplit(raw)
if not target.port or not 1 <= target.port <= 65535:
raise ValueError("Explicit local port required")
return target
def run(args):
target = local_target(args.target)
if args.check:
return {"checked": True, "network": False}
if not args.allow_local_write:
raise ValueError("--allow-local-write required; no request sent")
token = os.environ.get("REDUXHUB_TEST_TOKEN", "")
if not re.fullmatch(r"rh_user_[A-Za-z0-9_-]{43}", token):
raise ValueError("Ephemeral delegated LOCAL REDUXHUB_TEST_TOKEN required, not a developer key")
if not args.file or not args.name or not args.category:
raise ValueError("--file, --name and --category must describe disposable LOCAL data")
file = Path(args.file)
if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]{0,90}\.zip", file.name):
raise ValueError("Plain ASCII local.zip basename required")
def call(method, route, body=None, session=None, offset=None):
headers = {"Authorization": "Bearer " + token, "Accept": "application/json"}
if session:
headers["X-Upload-Session"] = session
if body is not None:
if isinstance(body, bytes):
headers["Content-Type"] = "application/octet-stream"
else:
body = json.dumps(body).encode("utf-8")
headers["Content-Type"] = "application/json"
headers["Content-Length"] = str(len(body))
if offset is not None:
headers["Upload-Offset"] = str(offset)
# http.client uses this numeric loopback only; no redirects, DNS or proxies.
connection = http.client.HTTPConnection("127.0.0.1", target.port, timeout=15)
try:
connection.request(method, "/public/v1" + route, body, headers)
response = connection.getresponse()
raw = response.read(65537)
if not 200 <= response.status < 300 or len(raw) > 65536:
raise ValueError("Local response rejected; inspect status, never blindly replay writes")
payload = json.loads(raw)
if payload.get("success") is not True or not isinstance(payload.get("data"), dict):
raise ValueError("Invalid local API envelope")
return payload["data"]
except (OSError, http.client.HTTPException):
raise ValueError("Ambiguous local request; stop. Query status with the same credentials before manual recovery") from None
finally:
connection.close()
with file.open("rb") as source:
size = os.fstat(source.fileno()).st_size
if not 22 <= size <= MAX_FILE:
raise ValueError("ZIP must be 22 bytes through 256 MiB")
digest = hashlib.sha256()
for chunk in iter(lambda: source.read(CHUNK), b""):
digest.update(chunk)
source.seek(0)
created = call("POST", "/upload-sessions", {"name": args.name, "category": args.category,
"filename": file.name, "bytes": size, "sha256": digest.hexdigest()})
if (not re.fullmatch(r"[a-f0-9-]{36}", created.get("id", ""))
or not re.fullmatch(r"rh_upload_[A-Za-z0-9_-]{43}", created.get("sessionToken", ""))
or created.get("offset") != 0 or created.get("maxChunkBytes") != CHUNK):
raise ValueError("Invalid session response; stop")
route = "/upload-sessions/" + created["id"]
session = created["sessionToken"] # Memory only: never print/save it.
offset, state = 0, created.get("state")
while offset < size:
status = call("GET", route, session=session)
if status.get("offset") != offset or status.get("state") != "uploading":
raise ValueError("Unexpected authoritative offset/state; no automatic resume")
chunk = source.read(min(CHUNK, size - offset))
if not chunk:
raise ValueError("Local file changed")
appended = call("PATCH", route, chunk, session, offset)
if appended.get("offset") != offset + len(chunk):
raise ValueError("Ambiguous append; stop without replay")
offset, state = appended["offset"], appended.get("state")
if state != "staged":
raise ValueError("Final chunk was not staged; do not commit")
if not args.commit_local:
return {"state": "staged", "note": "Reservation remains; not published"}
result = call("POST", route + "/commit", {}, session)
if result.get("state") != "committed" or result.get("status") != "pending":
raise ValueError("Ambiguous commit; do not replay")
return {"state": "committed", "status": "pending"}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--target", required=True)
parser.add_argument("--allow-local-write", action="store_true")
parser.add_argument("--commit-local", action="store_true")
parser.add_argument("--check", action="store_true")
for key in ("file", "name", "category"):
parser.add_argument("--" + key)
try:
print(json.dumps(run(parser.parse_args())))
except (ValueError, OSError):
# Do not include response bodies, token values or HTTP exception objects.
parser.exit(1, "Local upload stopped. Validate input/permissions and inspect session status before any manual retry.\n")
if __name__ == "__main__":
main()