PUBLIC API · v1
ДОКУМЕНТАЦИЯ

Операции автора

Загрузка файлов, изменение описания и проверка статуса.

API https://api.reduxhub.ru/public/v1

DL https://dl.reduxhub.ru

Только справка · запросов нет

Условия доступа#

УсловиеПроверка
ПриложениеЯвное согласие и нужные области доступа: mods:create + files:upload для загрузки, mods:update для описания мода.
ПользовательДелегированный токен rh_user_, текущее разрешение mods.upload или другое необходимое разрешение; соответствие требованиям к авторам.
РесурсПроверка владельца, видимости и разрешённых полей; повторная проверка перед завершением загрузки.
Ключ и тарифКлючи rh_live_ — только для чтения. Оплата не даёт права загрузки и редактирования, доступа к платному контенту или привилегий модератора.

Что исключено#

Методы записи#

МетодНазначение
POST /mods; POST /uploads/externalСсылка на Google Drive: name, category, googleDriveFileId и разрешённые поля описания. Регистрирует мод для модерации, не передаёт файл.
PATCH /mods/{id}Изменение только своего мода: name/category/description/type/version/project, по схеме и текущим правилам.
GET /mods/{id}/upload-statusСтатус загрузки своего мода по делегированному токену; без внутренних файлов и токенов.
POST /upload-sessionsСоздание сессии загрузки ZIP; протокол и лимиты ниже.
GET/PATCH /upload-sessions/{id}; POST /upload-sessions/{id}/commitПроверка статуса, последовательная передача частей файла и завершение загрузки. Мод создаётся бесплатным и ожидает модерации.

Загрузка ZIP · 15 минут#

  • POST /upload-sessions: JSON с name, category, filename, bytes и sha256 (64 шестнадцатеричных символа в нижнем регистре). Необязательные поля: description/type/version/project. filename — имя ZIP без пути, например local.zip. Часть имени до .zip содержит от 1 до 91 символа: латинские буквы, цифры, дефисы и подчёркивания; первый символ — буква или цифра.
  • В data ответа: id (UUID), offset=0, sessionToken (показывается один раз), expiresIn=900 и maxChunkBytes=1048576. Храните sessionToken только в памяти на время сессии.
  • GET требует тот же Bearer и X-Upload-Session. PATCH также требует Upload-Offset, Content-Type: application/octet-stream и точный Content-Length (1..1048576). Тело — байты файла, без сжатия и потоковой передачи chunked. Заголовки TUS не поддерживаются.
  • Последний PATCH переводит допустимый ZIP в staged, но не публикует его. Для POST /upload-sessions/{id}/commit передайте JSON {}. Повторно проверяются хеш, длина, архив, лимит хранения, согласие и текущие права. Результат — committed с status=pending.

Лимиты и безопасность файлов#

  • От 22 байт до 256 MiB на ZIP; часть файла — до 1 MiB; сессия действует 15 минут. У пользователя может быть одна активная публичная сессия на все выданные разрешения и проекты.
  • Общий резерв загрузок — до 2 GiB, на пользователя — до 1 GiB; также действует лимит хранения автора. После завершения или при неопределённом результате резерв сохраняется. Это отдельное ограничение, не квота запросов за тарифный период.
  • Принимается только ZIP: до 10000 записей и до 512 MiB заявленного распакованного размера. Зашифрованные файлы, символические ссылки, вложенные архивы и пути за пределы архива запрещены. Эти проверки не заменяют антивирусную проверку и не подтверждают полную распаковку или CRC всех файлов.
  • Мод создаётся бесплатным, с нулевой ценой и статусом ожидания модерации. Используйте только поля схемы: нельзя менять владельца, издателя, цену или условия доступа.

Если ответ на запись потерян#

Примеры загрузки в локальной тестовой среде#

Запускайте примеры только в изолированной локальной тестовой среде с тестовым ZIP и делегированным тестовым токеном. Скрипты отклоняют внешние адреса и ключи разработчика для чтения; запросы разрешаются только явными флагами запуска. Секреты не выводятся и не сохраняются.

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 · ZIP до 1 MiB
cURL · 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 · части до 1 MiB
Node.js · части до 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 · стандартная библиотека
Python · стандартная библиотека
"""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()

ReduxHub Developers · API 1.0.0