Frequently asked questions

The key documents are public: site rules, terms of use, privacy policy and cookie policy. These links open in the currently selected site language.

Yes. The public API now has stable catalog reads with cursor-first keyset pagination, direct-to-storage creator upload sessions with status/complete/abort lifecycle endpoints, async job processing through GET /v1/uploads/{upload_id}, Mod Manager download/install-plan endpoints, and delegated Agent Gateway tools under the v1 contract. Catalog cursors are opaque v1 tokens bound to the resource, normalized filters, sort, and first-page insertion snapshot. Reusing one with a changed context returns 400, and rows inserted after page one remain outside that cursor's snapshot.

A successful version write confirms a committed private/no-store result. Anonymous catalog/version GET revalidates shared cache on every reuse; the catalog freshness p95 SLO is 15 seconds and search index is 30 minutes. Mod/ModVersion PATCH sends a strong ETag in If-Match: missing returns 428 and a stale validator returns 412 with the current ETag. Before provider signing, download resolve limits concurrency to 2 anonymous or 4 authenticated leases per actor and 16 per client. The cached PublicModVersion artifact expansion requires scan_status=clean, lifecycle=ready, and publication state=published and remains eventual. Direct download resolve and install plan are private point-in-time reads over an eligible target whose established database state may be approved or published; direct targets are not published-only and not legacy-only. Upload status shows current database state at request time, worker transitions are eventual, and progress.available=false means unknown, not zero. Webhooks are feature-gated: when enabled, delivery is eventual, at-least-once, replayable, and unordered; while either gate is disabled, no delivery is promised.

Current status, available endpoints, and future integration rules are collected on the API page.

The Upload API is for authors, teams, CI pipelines, and tools that want Publish to Moddingflow without walking through the browser form for every release. Build locally or with GitHub Actions, upload direct-to-cloud, wait for scan/validation, and publish a new version only when the API returns ready.

Use individual API keys or OAuth/PAT tokens instead of sharing the main account password. Before creating a session, CI can call POST /v1/uploads:validate; this validate-only check neither creates an upload nor writes bytes. Create with one stable Idempotency-Key per logical upload: retrying the same body reuses the same durable reservation without charging the byte quota twice, while a changed body conflicts. Large archives use resumable Cloudflare R2 multipart upload: poll status.progress and completedParts, refresh only missing part URLs, and keep the same session for up to 48 hours while each signed URL stays short-lived. If a file fails validation, hits quota, duplicates a version, or enters quarantine/review, the client gets a machine-readable status, an error code such as duplicate_version, and a request_id for support; an aborted session returns lifecycleStatus cancelled. In production, publication requires a clean malware verdict: clearly dangerous or infected archives are rejected, while nested archives, executables, and unverified RAR/7z files remain in private quarantine until MFA-authenticated staff review. The account inbox attempts a deduplicated notification for a failed scan, required review, and successful publication, but notification arrival is not the lifecycle acknowledgement; clients must keep polling the machine-readable status.

When complete returns an AsyncJob, the service has first isolated the uploaded bytes in a private server-only seal; checksum, validation, scan, and final copy read that immutable seal rather than the client-writable staging key. You never receive or manage the seal key. Poll job.statusEndpoint: queued and processing are non-terminal; succeeded, rejected, failed, and cancelled are terminal. job.progress reports a truthful 0/1 completion unit instead of an estimated scanner percentage. Use createdAt, updatedAt, startedAt, completedAt, retry.attempt, retry.maxAttempts, retry.nextAttemptAt, retry.retryable, and Retry-After to diagnose waiting or retrying work. A terminal failure returns a stable reason code, never raw provider prose.

Automation should also use complete's HTTP status: queued or processing returns 202 Accepted with Location equal to job.statusEndpoint. An already terminal job, including a replay of the same completed result with the original Idempotency-Key, returns 200 OK without repeating the operation.

Each team member creates an individual resource-scoped key through POST /v1/api-keys and never receives the owner session cookie. Create and rotate require Idempotency-Key. Reusing the same header with the same request never repeats the credential mutation; because the raw secret is never persisted, a completed replay returns idempotency_replay_unavailable without operation-shaped committed metadata. Inspect the key through GET /v1/api-keys or revoke it before starting a new mutation. The raw secret is a one-time reveal, the server stores only token_hash and a safe fingerprint, and GET /v1/api-keys/capabilities shows available scopes and projects. owner, maintainer, publisher, and reviewer roles bound mods:write, versions:write, files:upload, versions:publish, versions:archive, files:manage, and teams:admin. Rotate with POST /v1/api-keys/{api_key_id}/rotate, revoke with DELETE /v1/api-keys/{api_key_id}, and use last_used_at plus key id/fingerprint in audit without any secret.

Do not share one owner key, owner password, or session cookie. Give each person an individual resource-scoped key for the target mod with the smallest scopes needed for their role. Assign owner, maintainer, publisher, or reviewer access in Settings > Developer. The raw secret is a one-time reveal.

Review last_used_at and the safe key fingerprint, rotate a key during planned replacement, and revoke it immediately after suspected exposure or when a teammate leaves. Audit records identify the actor and key without storing or displaying the secret.

Do not publish, rename, or repackage an archive to bypass a failed scan. A rejected or uncertain file stays private with failed or quarantined/review status. Open Settings > Developer or call GET /v1/uploads/{upload_id}, then keep supportCorrelationId (also returned as X-Upload-Correlation-Id), request_id, trace_id, and an error code such as av_scan_rejected for support. The correlation id is safe to share with support but never replaces authorization.

Known dangerous or infected archives are rejected. Files that need more evidence remain private for manual review. Follow the returned recovery details, wait for review when requested, and create a new session only after fixing the identified source or archive problem.

Both paths use the same upload-session backend, private Cloudflare R2 storage, validation, scan, and quarantine/review gates. The manual browser form is a guided choice for occasional releases. API upload is designed for repeatable local tools and CI, with Idempotency-Key retries, resumable multipart transfer, status.progress, and machine-readable failures.

Automation does not weaken the security checks or make a file public earlier. Choose the interface that fits the workflow; the same security gates must report ready before publish.

For a signed single PUT, both clients must send every returned header, including If-None-Match: *. A conditional 412 means an ambiguous existing write, not permission to overwrite: call the same complete endpoint, then server verification through HEAD, the immutable seal, and SHA-256 determines the outcome.

Yes. Use the official GitHub Action or CLI and store MODDINGFLOW_API_KEY in a GitHub environment or repository secret. Never place it in workflow YAML, repository variables, logs, command arguments, artifacts, or a committed state file.

Use a resource-scoped, least-privilege key, prefer a protected environment with approval for staging and production, keep permissions: contents: read unless the workflow proves it needs more, and pin the Action to a reviewed 40-character commit SHA. Rotate or revoke the key after exposure. See the API docs for the complete workflow.

Start with the API docs, then open the API reference or download the OpenAPI JSON. The SDK is a repo-only source artifact until package publishing and is not published to npm, PyPI, or NuGet yet; open the SDK source page, then use local imports from sdk/csharp/Moddingflow.PublicApi, sdk/typescript/src/moddingflow-public-api.ts, or sdk/python/moddingflow_public_api.

The current support and EOL matrix is documented in docs/public-api/SDK-SUPPORT-AND-EOL.md. These are Preview source artifacts: package and contract versions are separate, and no registry publication, support SLA, signature, or stable EOL promise is implied before an immutable stable release.

No. Deprecation is a migration signal, not an immediate runtime behavior change. Stable v1 keeps old clients working during at least 90 days or two stable API releases of notice, whichever gives the safer migration window.

Deprecated operations or capabilities use the Deprecation and Sunset response headers when they can be signaled at HTTP response time, plus a migration guide and changelog entry. During the notice window old clients keep the same status codes, same field types, aliases, scopes, Problem Details codes, cursor semantics, and upload/download/webhook lifecycle behavior. The repository release gate rejects Sunset unless a committed migration guide, a ready non-deprecated replacement, dated telemetry evidence, and a support plan with an explicit owner and approver are bound to the same deprecation and sunset dates.

Release notes, migration guides, and changelog entries for deprecation paths are tracked on the API changelog.

The public API auth lifecycle uses OAuth under https://api.moddingflow.com. Developers register self-service user applications in Settings > Developer at /account/developer/applications. Authorization Code + PKCE always shows explicit consent for the requested scopes and states that approved permissions apply to every resource the account is eligible to access; resource-restricted automation uses a PAT instead. Basic read and install scopes are approved automatically for the application, while sensitive scopes require review and a recent AAL2 2FA step-up before consent can complete. The client receives a short-lived access token and must not store the user password. OAuth access tokens authorize API calls; an optional OpenID Connect ID token only confirms identity to the client. OIDC clients request openid with a fresh nonce and validate the RS256 signature, issuer, audience, time claims, and nonce through discovery/JWKS. If OIDC discovery is unavailable, clients must stay OAuth-only.

Device Flow clients must honor interval and slow_down backoff, and the user can deny a request with access_denied. Refresh tokens rotate on every refresh, and reuse of an older token immediately revokes the entire refresh family. Personal Access Tokens are shown once, stored only as hashes, and support create-before-revoke rotation with a maximum 10-minute overlap, scopes, expiry, last used timestamps, and audit trails. Every API request needs a meaningful ApplicationName/ApplicationVersion User-Agent; PAT mutations also need stable X-Moddingflow-Client and X-Moddingflow-Client-Version headers. Invalid identity returns invalid_client_identity before rate limiting or a business change. The current contract details are on the API page.

The public API applies route, body-size, byte-budget, per-user, per-application, and per-token limits before storage, signing, upload, download, RPC, or Agent Gateway side effects. Oversized request bodies return 413. Overloaded or abusive clients receive 429 as application/problem+json with Retry-After plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset when a bucket is available; retry with backoff after that window. For a download-specific 429, keep download_job.id, grant_id, bytes_received, etag, and next_attempt_at, then resend job_id with monotonic progress after Retry-After; the server keeps the same job and reserved grant without another provider effect.

Operational dashboards and audit trails group these events by client_id, actor_user_id, token_id_or_api_key_id, scope, and token_kind so maintainers can distinguish normal traffic spikes from token abuse.

Public API webhooks use owner-scoped subscriptions and stable event names: mod.updated, version.published, file.ready, file.failed, upload.completed, scan.completed, token.changed, and app.changed. Each delivery body includes delivery_id, kind, created_at, and data, and each request is signed with X-Moddingflow-Signature using HMAC-SHA256 over `${timestamp}.${raw_body}` plus X-Moddingflow-Timestamp.

Webhook delivery is at-least-once, replayable, and unordered. A receiver should return 2xx quickly, process asynchronously, reject stale timestamps, deduplicate business effects by event_id, keep delivery_id for diagnostics, and fetch the latest resource state before applying changes. Use GET /v1/webhook-deliveries for attempt history and POST /v1/webhook-deliveries/{delivery_id}/redeliver with Idempotency-Key for a linked redelivery. Repeated terminal failures can disable the subscription. The full contract is on the API page.

Only through delegated Agent Gateway tokens. The agent receives a short-lived token with audience agent-gateway, narrow scopes, and actor/delegation metadata; it does not receive your full user session token.

Read tools can search mods, read mod details, resolve install plans, compare versions, and safely resolve downloads. Write-capable tools run as dry-runs by default, and publish, delete/archive, permission, or paid/restricted access changes require explicit confirmation.

No. The Public API uses stable UUIDs or lifecycle ids for games, mods, builds, versions, logical files, physical blobs, upload sessions, download grants, tokens, and webhook deliveries where those resources are public. Internal forum/topic IDs remain website details and are not the external contract.

This lets old pages keep working while the Mod Manager and integrations receive canonical resources without forum naming leaks. Slugs, filenames, storage object names, and hashes are aliases or verification data, not durable external keys. Renames, metadata rebuilds, and slug changes keep public IDs; replacing file bytes creates a new physical blob and may create a new logical artifact/version binding.

The site supports Russian, English and German. The main interface language is selected in Settings and saved in your profile and cookie.

Content language selection remains only in regular forum sections, where it helps show topics in the chosen language. Mod catalogs, build catalogs, and search show every language by default.

While you type, the site shows lightweight suggestions from titles, authors, games and tags. Full hybrid search runs after you submit the query: exact matches are scored from titles, tags and search terms, while semantic search helps find relevant text.

New mods, builds, topics and replies enter the search index through a background worker. This is usually quick, but a newly published item can appear in search after a short delay.

No. Public IDs are opaque UUIDs and do not depend on a slug, title, filename, URL, CDN, hash, or storage address. Renames and metadata-only edits keep the ID. New bytes create a new Blob and, when the logical file or version changes, a new Artifact or Version ID.

Archived and withdrawn resources can be restored through an allowed lifecycle transition. Permanent deletion leaves a tombstone: lookup returns HTTP 410 Gone, and the old ID and source binding are never assigned to another resource.

Wait a moment, then use the manual open button if your browser blocked the new tab. Keep the Moddingflow page open until the download link appears.

If the download still fails, try again after changing your network or VPN route. The site checks the primary Cloudflare route before using the backup CDN.

Cloudflare R2 remains the main source for mod archives. Bunny CDN is only a pull-CDN fallback when the primary route is unavailable for you.

Fallback links are short-lived and file-specific. They are not permanent public mirrors and do not bypass download limits, content warnings or account checks.

The Mod Manager first requests an install plan with game version, platform, loader, release channel, typed required/optional/conflict/embedded dependencies, selected artifacts, decision reasons, stable plan/item IDs, install order, expected archive layout, warnings, and per-file hashes. Identical normalized input over unchanged catalog data returns the same IDs; embedded dependencies do not add a download step, and optional steps are included only when requested. Download resolve then creates a short-lived download grant and returns the primary/fallback route, the legacy sha256 alias, hashes.sha256 as the canonical SHA-256 verifier, size_bytes, and resume policy. SHA-256 verifies the complete stored object: the client assembles every Range part, checks size_bytes, and only then verifies the digest. ETag is an opaque validator for one transport representation and conditional resume; it is not a cryptographic digest or file identity and does not carry across providers. The resolve endpoint returns a 200 JSON grant, does not use a 302 redirect, and does not stream binary data. The current signed transport does not guarantee RFC 9530 Content-Digest or Repr-Digest. SHA-1 or MD5 may appear only as optional compatibility metadata.

A version response may also include PublicModVersion.artifacts. This is an optional expansion only for a managed primary artifact with size_bytes > 0, exact sha256/hashes.sha256, an actual AV scan_status=clean result from the current upload session matched by both file_id and final_blob_id, lifecycle=ready, publication state=published, and managed resolve eligibility. Stable artifact_ids remain available; for a legacy artifact, artifacts is omitted instead of being filled with fabricated metadata. download_metadata contains only a relative resolve_endpoint and truthful range_supported value: it never contains a provider URL, and clients must not construct or persist one.

Yes. If your VPN makes Cloudflare reachable, the download uses the primary Cloudflare R2 link.

If the browser cannot fetch the Cloudflare probe, Moddingflow can request a short-lived Bunny fallback link for the same archive.

Check that your email is typed correctly, that the password matches the form requirements and that the confirmation email is not in spam. If the confirmation link expired, start registration again.

If the account already exists, try to sign in or reset the password from the sign-in page.

An account lets you publish topics, mods, builds and guides, leave comments, react to content, watch materials and manage your public profile.

After signing in, open your account area to manage profile, security and subscription settings.

The archive uploads directly from your browser to Cloudflare R2 through a short-lived signed URL. This is Moddingflow's primary storage for mod and build archives.

The site creates an upload session and verifies the file before publication. The privacy policy explains which technical data Cloudflare/R2 and Moddingflow may process.

Regular accounts can publish up to 3 main files at 500 MB each and up to 5 optional files at 100 MB each. Premium keeps the same file slots but raises the size to 4 GB per main file and 250 MB per optional file. Minecraft uses a separate limit system.

You return to the mod upload screen, and the fields and selected files stay in place while the tab remains open.

Temporary images and files that were uploaded during the failed attempt are cleaned up automatically. After the error, check the message on the form and try publishing again.

Premium is a 30-day website subscription. It removes the download wait, raises mod archive upload limits, and unlocks GIF avatars, GIF banners, nickname font, gradient nickname and emoji status.

For regular mods, a free account can upload up to 3 main files at 500 MB each and up to 5 optional files at 100 MB each. Premium keeps the same slots but raises the size to 4 GB per main file and 250 MB per optional file. Minecraft uses separate limits.

Premium does not promise increased download speed, premium support or priority support replies. Subscription management is available in your account area.

Change your nickname in the account profile section. After saving, check the public profile page to make sure the name, avatar and description look right.

Open the billing page, sign in and choose the Premium purchase action. Checkout runs on Stripe, and card details stay with Stripe.

Premium is purchased in 30-day periods. The current price is shown on the billing page before payment, and you must confirm that access starts immediately after successful payment.

Cancellation is available on the billing page. Use the renewal cancellation action if you want to stop the next automatic charge.

After cancellation, Premium remains active until the current paid period ends. If an exact access end date is available, it is shown in the billing section.

Premium runs in 30-day periods. When automatic renewal is enabled, Stripe schedules the next charge at the start of the next period.

If renewal is cancelled, no next automatic charge is scheduled, and Premium stays available until the already paid period ends.

A 14-day contract withdrawal may be available for the first Premium checkout or a trial-to-paid conversion. Ordinary automatic renewal does not create a new automatic 14-day window.

When withdrawal is available, the billing page shows the withdrawal action and the unused-period calculation. If automatic refund processing is unavailable, the request goes to manual review or another documented remedy.

Receipts open from the billing page on Stripe-hosted pages. Card details are managed only in Stripe Portal.

If you contact support about a payment, include the account email and Stripe receipt ID. Do not send card numbers, CVC codes or screenshots with full payment details.

Open your account area. It lists your topics, posts, mods, builds and other public materials when they are connected to your account.

Profile, avatar, cover and bio are edited in the account area. Upload only supported image formats and do not use someone else's material without permission.

If you use Premium profile styling, make sure GIFs and visual effects still follow the site rules.

The public profile shows your display name, avatar, bio and public publications. Private payment data, email, security settings and internal records are not shown.

Account data handling is described in the privacy policy.

A build author can add a dedicated questions and answers block while publishing or editing a build. It is meant for installation notes, conflicts, requirements and playthrough details.

That block appears on the build page in the FAQ or Questions and answers tab. It is separate from this general support FAQ.

If you are signed in, change the password in the security settings of your account area. If you cannot sign in, use password recovery from the sign-in page.

Two-factor authentication is enabled in the security section of the account area. Keep backup access to your authenticator app before signing out.

Yes. In Settings > Developer you can disable an OAuth application or rotate and revoke your personal access tokens and API keys. Disabling an application is enforced immediately: new authorization and token requests stop, and access tokens issued to that application are rejected. Revoking OAuth access through https://api.moddingflow.com/oauth/revoke revokes its refresh family, while reuse of an older refresh token also revokes the whole family. PAT rotation allows the previous secret for no more than a 10-minute overlap so clients can switch safely; explicit revoke is immediate.

Start with password recovery from the sign-in page and check your email. If the account was blocked by moderation, read the reason carefully and compare it with the site rules.

Account deletion starts from the account area when that feature is available for your profile. Download any data you want to keep before deleting the account.

Some public materials may be retained or anonymized when needed for discussion integrity, safety, legal duties or moderation. Details are explained in the privacy policy.

Data export is available in the account area. It helps you get a copy of profile data and related records that the site can provide to the user.

Large record sets are exported in capped sections. If a section is capped, the JSON file includes continuation metadata so support can identify what remains.

For the legal basis of data processing, read the privacy policy.

Open the content report action from the site footer and include links to the original, the disputed publication and proof of authorship. A precise report helps moderators understand the issue faster.

Forbidden actions with other people's mods and files are described in the site rules.

You may publish a translation only when the original author, license or source platform rules allow it. Credit the author, link the original and state the usage terms.

If permission is missing or redistribution is forbidden, do not upload someone else's files. You can publish instructions and link to the original mod instead.

The full version is on the site rules page. Check it before publishing mods, builds, translations or sensitive content.

Do not publish pirated files, stolen mods, malware, stealers, miners, doxxing, harassment, illegal content, DRM cracks, warez or material that breaks game or platform rules.

NSFW and 18+ content has separate restrictions. Check the site rules before publishing.

Moderation may hide content, remove a file, issue a warning, restrict account actions or block an account. The action depends on the violation, account history and risk to users.

Removing one item does not mean the rest of an author's content is automatically approved. Each questionable item can be reviewed separately.