Die Upload API ist für Autoren, Teams, CI pipelines und tools gedacht, die Publish to Moddingflow nutzen wollen, ohne bei jedem release durch die browser form zu gehen. Baue lokal oder mit GitHub Actions, lade direct-to-cloud hoch, warte auf scan/validation und veröffentliche eine new version erst, wenn die API ready zurückgibt.
Nutze individual API keys oder OAuth/PAT tokens statt das main account password zu teilen. Vor dem Erstellen einer Session kann CI POST /v1/uploads:validate aufrufen; diese validate-only Prüfung erstellt keinen Upload und schreibt keine Bytes. Nutze einen stabilen Idempotency-Key pro logischem Upload: Ein Retry mit demselben Body verwendet dieselbe durable Reservation, ohne das Byte-Quota doppelt zu belasten; ein geänderter Body führt zum Konflikt. Große Archive nutzen resumable multipart upload in Cloudflare R2: status.progress und completedParts abfragen, nur URLs für missing parts erneuern und dieselbe Session bis zu 48 Stunden fortsetzen, während jede signed URL kurzlebig bleibt. Wenn eine Datei validation nicht besteht, quota erreicht, eine version dupliziert oder in quarantine/review geht, erhält der client einen machine-readable status, einen error code wie duplicate_version und eine request_id für support; eine abgebrochene Session liefert lifecycleStatus cancelled. In production erfordert die Veröffentlichung ein clean malware verdict: eindeutig gefährliche oder infizierte Archive werden abgelehnt, während nested archives, executables und ungeprüfte RAR/7z-Dateien bis zur MFA-geschützten staff review in private quarantine bleiben. Die Account Inbox versucht eine deduplizierte Benachrichtigung bei failed scan, required review und erfolgreicher Veröffentlichung, aber deren Ankunft ist kein Lifecycle Acknowledgement; Clients müssen den machine-readable Status weiter pollen.
Wenn complete einen AsyncJob liefert, hat der Service die hochgeladenen Bytes zuerst in einem privaten server-only Seal isoliert; Checksum, Validation, Scan und Final Copy lesen diesen immutable Seal statt des client-writable Staging Keys. Der Seal Key wird dem Client nicht ausgegeben und muss nicht verwaltet werden. Frage job.statusEndpoint ab: queued und processing sind non-terminal; succeeded, rejected, failed und cancelled sind terminal. job.progress zeigt ehrlich 0/1 completion statt eines geschätzten scanner percentage. Nutze createdAt, updatedAt, startedAt, completedAt, retry.attempt, retry.maxAttempts, retry.nextAttemptAt, retry.retryable und Retry-After zur Diagnose von wartender oder erneut versuchter Arbeit. Ein terminal failure liefert einen stabilen reason code, niemals raw provider prose.
Automation sollte auch den HTTP-Status von complete auswerten: queued oder processing liefert 202 Accepted mit Location gleich job.statusEndpoint. Ein bereits terminaler Job, einschließlich eines Replays desselben abgeschlossenen Ergebnisses mit dem ursprünglichen Idempotency-Key, liefert 200 OK, ohne die Operation zu wiederholen.
Jedes team member erstellt einen eigenen resource-scoped key über POST /v1/api-keys und erhält niemals die owner session cookie. Create und rotate erfordern Idempotency-Key. Derselbe Header mit demselben Request wiederholt die credential mutation nicht; weil das raw secret niemals gespeichert wird, liefert ein abgeschlossener Replay idempotency_replay_unavailable ohne operation-shaped committed metadata. Prüfe den Key über GET /v1/api-keys oder widerrufe ihn, bevor eine neue Mutation gestartet wird. Das raw secret wird one-time gezeigt, der Server speichert nur token_hash und safe fingerprint; GET /v1/api-keys/capabilities zeigt scopes und projects. Die Rollen owner, maintainer, publisher und reviewer begrenzen mods:write, versions:write, files:upload, versions:publish, versions:archive, files:manage und teams:admin. Rotation läuft über POST /v1/api-keys/{api_key_id}/rotate, revoke über DELETE /v1/api-keys/{api_key_id}; last_used_at und key id/fingerprint bleiben ohne secret im audit.