Salt la conținut

Documentația API

Încarcă un fișier o dată, trimite-l pe hosturile de fișiere alese și primește înapoi un singur link de partajare — din propriul cod.

Actualizat

Un API REST versionat: încarci un fișier pe bucăți, îl trimiți pe hosturile alese, iar toate copiile sunt adunate pe o singură pagină de partajare, cu stare live.

URL de bază
https://api.mirroruploadx.com/api/v1
Autentificare
x-api-key: mux_…
  1. 1Deschide o sesiune

    POST /api/v1/upload-sessions

    filename + sizeBytes; primești sessionId și chunkSize

  2. 2Trimite bucățile

    PATCH /api/v1/upload-sessions/{id}/chunks

    octeți bruți, în ordine; răspunsul care completează fișierul conține fileId

  3. 3Distribuie

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; apoi interoghează jobul

Creează o cheie pe pagina Chei API. Ghidul complet, cu cod, se află în Încărcare și distribuire.

Autentificare

Creează o cheie pe pagina Chei API din panoul tău. Cheia completă (începe cu mux_) este afișată o singură dată, așa că salveaz-o imediat. Trimite-o în headerul x-api-key la fiecare cerere; Authorization: Bearer mux_… este acceptat la fel, pentru clienții care folosesc doar tokenuri bearer.

Cheile au permisiuni limitate: o cheie ajunge doar la endpointurile acoperite de permisiunile ei, iar un apel cu permisiunea greșită returnează 403 INSUFFICIENT_SCOPE, cu permisiunea necesară în mesaj. Setările contului, gestionarea cheilor și webhookurile nu sunt deloc accesibile cu o cheie API (API_KEY_NOT_ALLOWED).

PermisiuneAcces la
upload:writeSesiuni de încărcare (creare, bucăți, finalizare, anulare), cota ta de încărcare, suspendarea sau modificarea distribuirii automate a unei încărcări (hold-distribution, distribution-intent), încărcări de la URL, pornirea distribuirii
file:readListarea fișierelor, detaliile fișierelor, starea oglinzilor și a joburilor
file:writeSetările de partajare ale unui fișier
file:deleteȘtergerea unui fișier și a oglinzilor lui

Endpointuri

Tot ce poate accesa o cheie API, plus endpointurile publice care nu necesită cheie. Când coloana de permisiuni listează două permisiuni, oricare dintre ele este suficientă. Schemele de cerere și răspuns pentru fiecare se află în referința API.

MetodăCalePermisiuneCe face
POST/api/v1/upload-sessionsupload:writeDeschide o sesiune de încărcare (opțional cu un plan de distribuire)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeTrimite următoarea bucată de octeți
HEAD/api/v1/upload-sessions/{id}upload:writeDe unde se reia: headerul Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readStarea sesiunii: octeți primiți, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readLimitele tale de încărcare, consumul și sesiunile nefinalizate
POST/api/v1/upload-sessions/{id}/completeupload:writeFinalizează o încărcare al cărei răspuns final s-a pierdut (sigur la reîncercare)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeÎmpiedică pornirea automată a unei distribuiri amânate
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeÎnlocuiește planul de distribuire al unei încărcări
DELETE/api/v1/upload-sessions/{id}upload:writeAnulează o încărcare nefinalizată și eliberează-i locul
POST/api/v1/remote-uploadsupload:writePreia fișiere de la URL-uri http(s) în contul tău
POST/api/v1/mirror-tasks/startupload:writeTrimite un fișier pe hosturile alese
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readStarea jobului, fiecare host și linkul de partajare (shareTakenDown semnalează o pagină eliminată)
GET/api/v1/filesfile:readListează fișierele tale (paginare cu cursor, căutare, filtre)
GET/api/v1/files/{id}file:readUn fișier: mărime, sumă de control, job, setări de partajare, statistici
GET/api/v1/files/{id}/mirrorsfile:readToate copiile unui fișier: host, link, stare, clicuri
PATCH/api/v1/files/{id}/sharefile:writeParola de partajare, expirarea, vizibilitatea
DELETE/api/v1/files/{id}file:deleteȘterge un fișier și (implicit) copiile lui de pe hosturi
GET/api/v1/platformniciuna (public)Limitele curente: cel mai mare fișier, hosturi per fișier, plafoane pentru încărcarea de la URL
GET/api/v1/providersniciuna (public)Catalogul de hosturi, cu slugurile pe care le trimiți în providerSlugs
GET/api/v1/providers/statusniciuna (public)Rata de reușită măsurată la încărcare, per host
GET/api/v1/stats/publicniciuna (public)Totalurile platformei pentru ultimele 30 de zile: fișiere, oglinzi live, rată de reușită

Încarcă un fișier și distribuie-l

  1. Deschide o sesiune cu POST /api/v1/upload-sessions. filename și sizeBytes (lungimea exactă în octeți) sunt obligatorii; mimeType și un UUID idempotencyKey sunt opționale — repetarea unei cereri cu aceeași cheie returnează sesiunea existentă în loc să deschidă una nouă. Răspunsul conține data.sessionId (nu id) și data.chunkSize.
  2. Trimite octeții cu PATCH /api/v1/upload-sessions/{id}/chunks: octeți bruți, tipul de conținut application/offset+octet-stream și poziția de început a bucății în headerul upload-offset. Bucățile se trimit în ordine sau cu până la maxChunksAhead bucăți înainte; dacă trimiți în ordine, folosește data.uploadedBytes din fiecare răspuns ca offset următor. Trimite bucăți de chunkSize octeți; fiecare bucată, cu excepția ultimei, trebuie să aibă cel puțin 5 MiB, iar o încărcare poate avea cel mult 10 000 de bucăți. Răspunsul care completează fișierul conține data.fileId. Pentru viteză mai mare, poți ține simultan în tranzit 2–3 bucăți ale aceluiași fișier. Trimite prima bucată singură; răspunsul ei oferă valoarea reală data.maxChunksAhead (4 dacă prima bucată a fost o felie întreagă de chunkSize, 0 = doar în ordine). Dacă prima bucată a fost o felie întreagă de chunkSize, fiecare bucată ulterioară trebuie să fie la fel (în ordine sau înainte): începe la un multiplu de chunkSize și are exact chunkSize octeți (ultima: restul fișierului). O bucată trimisă înaintea uploadedBytes trebuie să fie o astfel de felie și să înceapă cu cel mult data.maxChunksAhead bucăți înainte, altfel primește 409 CHUNK_MISALIGNED sau 409 CHUNK_OUT_OF_WINDOW. uploadedBytes numără doar octeții primiți fără goluri, iar bucata care completează fișierul, oricare ar fi ea, primește răspunsul cu fileId. Retrimiterea unei bucăți deja sosite este un succes inofensiv.
  3. Distribuie cu POST /api/v1/mirror-tasks/start: fileId și providerSlugs sunt obligatorii (slugurile provin din GET /api/v1/providers). Opționale: minSuccess (implicit 1 — câte hosturi trebuie să accepte fișierul pentru ca jobul să nu eșueze; este completed doar când și toate celelalte hosturi l-au preluat, altfel partially_completed. Hosturile care refuză acest tip de fișier nu sunt luate în calcul), sharePassword, expiresInDays sau expiresAt. Răspunsul conține uploadJobId, taskCount, shareSlug, alreadyStarted și skipped[] — un host care nu poate prelua acest fișier este omis, nu eșuat, așa că citește skipped[] (motivele sunt listate mai jos). Un fișier poate ajunge momentan pe cel mult 50 hosturi.
  4. Urmărește finalizarea cu GET /api/v1/mirror-tasks/{uploadJobId} la câteva secunde, până când data.terminal este true. Răspunsul listează fiecare host în tasks[] (providerSlug, status, mirrorUrl, errorCode) și linkul de partajare în data.shareUrl. data.shareTakenDown este true când acea pagină de partajare a fost eliminată și nu se mai deschide.

Cel mai mare fișier acceptat în prezent are 5,00 GB.

bash, necesită jq

set -euo pipefail
API=https://api.mirroruploadx.com
FILE=clip.mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')

# 1. Open an upload session
SESSION_JSON=$(curl -sS --fail-with-body -X POST "$API/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"filename":"clip.mp4","sizeBytes":'"$SIZE"',"mimeType":"video/mp4"}')
SESSION=$(echo "$SESSION_JSON" | jq -r .data.sessionId)
CHUNK=$(echo "$SESSION_JSON" | jq -r .data.chunkSize)

# 2. Send the bytes in order, one chunk per request
OFFSET=0
while [ "$OFFSET" -lt "$SIZE" ]; do
  dd if="$FILE" of=part.bin bs="$CHUNK" skip=$((OFFSET / CHUNK)) count=1 status=none
  REPLY=$(curl -sS --fail-with-body -X PATCH "$API/api/v1/upload-sessions/$SESSION/chunks" \
    -H "x-api-key: $MUX_API_KEY" \
    -H "upload-offset: $OFFSET" \
    -H "content-type: application/offset+octet-stream" \
    --data-binary @part.bin)
  OFFSET=$(echo "$REPLY" | jq -r .data.uploadedBytes)
done
FILE_ID=$(echo "$REPLY" | jq -r .data.fileId)

# 3. Distribute to the hosts you pick
JOB=$(curl -sS --fail-with-body -X POST "$API/api/v1/mirror-tasks/start" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"fileId":"'"$FILE_ID"'","providerSlugs":["gofile","pixeldrain"],"minSuccess":1}' \
  | jq -r .data.uploadJobId)

# 4. Poll until the job is terminal, then print the share link
until curl -sS --fail-with-body "$API/api/v1/mirror-tasks/$JOB" \
        -H "x-api-key: $MUX_API_KEY" > job.json \
      && [ "$(jq -r .data.terminal job.json)" = "true" ]; do
  sleep 5
done
jq -r '.data.status, .data.shareUrl' job.json

Exemple de răspunsuri

Deschiderea unei sesiuni răspunde cu 201. Fiecare bucată, cu excepția ultimei, răspunde cu { uploadedBytes, completed: false, expiresAt }; ultima conține fișierul. distribution apare doar dacă ai transmis un plan la deschiderea sesiunii (vezi mai jos).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (completează fișierul) → 200
{
  "success": true,
  "data": {
    "uploadedBytes": 10485760,
    "completed": true,
    "fileId": "…",
    "scan": "skipped",
    "distributable": true,
    "distribution": {
      "started": true,
      "uploadJobId": "…",
      "taskCount": 2,
      "shareSlug": "…",
      "skipped": []
    }
  }
}
POST /mirror-tasks/start → 202
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "taskCount": 2,
    "shareSlug": "…",
    "skipped": [],
    "alreadyStarted": false
  }
}
GET /mirror-tasks/{uploadJobId} → 200
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "status": "completed",
    "terminal": true,
    "shareSlug": "…",
    "shareUrl": "https://mirroruploadx.com/f/…",
    "shareTakenDown": false,
    "minSuccess": 1,
    "scan": "skipped",
    "tasks": [
      {
        "provider": "Gofile",
        "providerSlug": "gofile",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://gofile.io/d/…",
        "mirrorHidden": false
      },
      {
        "provider": "Pixeldrain",
        "providerSlug": "pixeldrain",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://pixeldrain.com/u/…",
        "mirrorHidden": false
      }
    ]
  }
}

Un prim start reușit răspunde cu 202; un nou apel pentru un job care rulează deja răspunde cu 200 și alreadyStarted: true. Când linkul unui host este păstrat privat conform politicii, mirrorUrl este null, iar mirrorHidden este true — pagina de partajare îl listează în continuare.

Renunță la al doilea apel

Transmite distribution când deschizi sesiunea, iar serverul începe distribuirea imediat ce fișierul este complet. Verifică data.distribution în răspunsul care completează fișierul: started: true înseamnă că jobul este în coadă (uploadJobId, shareSlug). Cu started: false și deferred: true, intenționat nu este încă nimic în coadă — vezi mai jos. Cu started: false și fără deferred, încărcarea a reușit, dar distribuirea nu a putut porni (error spune de ce): apelează POST /api/v1/mirror-tasks/start cu fileId. Un error împreună cu deferred: true înseamnă un eșec temporar (de exemplu, toate hosturile sunt ocupate sau în mentenanță): nu apela start și nu încărca fișierul din nou — serverul va reîncerca singur pornirea distribuirii începând cu autoStartAt (până la 5 încercări). Apelează hold-distribution ca să o oprești.

curl
curl -sS -X POST "https://api.mirroruploadx.com/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "sizeBytes": 10485760,
    "mimeType": "video/mp4",
    "distribution": { "providerSlugs": ["gofile", "pixeldrain"], "minSuccess": 1 }
  }'
# The reply to the final chunk then carries data.distribution:
#   { "started": true, "uploadJobId": "…", "taskCount": 2, "shareSlug": "…", "skipped": [] }
#   or { "started": false, "error": { "code": "…", "message": "…" } }

Adaugă deferred: true în distribution pentru o perioadă de grație: răspunsul final este { started: false, deferred: true, autoStartAt }, iar serverul pornește singur distribuirea la autoStartAt (aproximativ 2 minute mai târziu), dacă nu apelezi tu start înainte. Ca să oprești pornirea automată, apelează POST /api/v1/upload-sessions/{id}/hold-distribution (fără corp; autoStartAt devine null și pornești tu distribuirea). Ca să schimbi planul, apelează PUT /api/v1/upload-sessions/{id}/distribution-intent cu aceleași câmpuri ca distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): înlocuiește planul și ridică suspendarea, iar după ce încărcarea s-a terminat, pornirea automată se mută la cel puțin 2 minute după apel. Dacă distribuirea a pornit deja, ambele răspund cu 200, iar distribution-intent indică alreadyStarted: true.

Pornește în 30 de minute. Când o încărcare se termină și nu este pornită nicio distribuire, copia noastră a fișierului este ștearsă după 30 de minute (dacă un plan de distribuire încă așteaptă să devină disponibile hosturile, după cel mult 72 de ore; încărcările de la URL nu sunt afectate). După aceea, start și distribution-intent răspund cu 409 SOURCE_GONE, iar fișierul trebuie încărcat din nou.

Dacă răspunsul final se pierde

Apelează GET /api/v1/upload-sessions/{id}: un fileId înseamnă că fișierul există; finalizable: true înseamnă că toți octeții au sosit, iar POST /api/v1/upload-sessions/{id}/complete îl finalizează. Acest apel este sigur la reîncercare și nu creează niciodată un al doilea fișier. Un offset nepotrivit primește 409 CHUNK_OFFSET_CONFLICT — trimite HEAD pe sesiune și reia de la headerul ei Upload-Offset. Un nou apel start pentru un job care rulează nu este o eroare: primești 200 cu alreadyStarted: true.

Încărcare de la un URL

POST /api/v1/remote-uploads primește { "urls": [...] } și preia fiecare fișier pentru tine (permisiunea upload:write). Sunt preluate doar linkuri http și https, adresele de rețea private sunt refuzate și se urmează doar un număr limitat de redirecționări. O cerere conține cel mult 10 URL-uri (returnat de GET /api/v1/platform); împarte listele mai lungi.

Limita de mărime per fișier depinde de sursă. Când aceasta raportează mărimea fișierului, fiecare fișier poate avea până la 5,00 GB (limits.remoteUploadPassthroughMaxBytes); când nu o raportează, până la 100,0 MB (limits.remoteUploadMaxBytes). Numele fișierului provine din headerul Content-Disposition al sursei, dacă îl trimite; un nume fără extensie primește una pe baza tipului fișierului.

Cererea așteaptă cât timp se descarcă fișierele. Dacă conexiunea cade înainte, fișierul ajunge totuși în contul tău — îl găsești cu GET /api/v1/files. Fiecare fileId este apoi distribuit cu POST /api/v1/mirror-tasks/start, ca mai sus.

Când spațiul de stocare temporar este plin, întreaga cerere primește 503 TEMPORARILY_UNAVAILABLE cu details.reason: "staging_full" și un header Retry-After. Dacă un singur URL nu încape, acea intrare din results[] are ok: false și același cod; un rezultat per URL nu are header, așa că timpul de așteptare în secunde se află în details.retryAfter.

curl -sS -X POST "https://api.mirroruploadx.com/api/v1/remote-uploads" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"urls":["https://example.com/files/archive.zip"]}'

# One result per URL, in order. A failed URL does not fail the batch:
# {"success":true,"data":{"results":[
#   {"url":"https://example.com/files/archive.zip","ok":true,
#    "fileId":"…","scan":…,"distributable":true}
# ]}}
# or {"url":"…","ok":false,"code":"REMOTE_TOO_LARGE","error":"…"}
#
# Then distribute each fileId with POST /api/v1/mirror-tasks/start.

Gestionarea fișierelor

Fișierele tale rămân în cont după încărcare. Listează-le cu GET /api/v1/files (limit până la 100; transmite nextCursor din răspuns ca cursor pentru pagina următoare, q caută după nume). GET /api/v1/files/{id} returnează un fișier cu jobul, setările de partajare și statisticile de vizualizare; GET /api/v1/files/{id}/mirrors listează fiecare copie cu linkul, starea și clicurile ei.

PATCH /api/v1/files/{id}/share (permisiunea file:write) modifică pagina de partajare: password (4–128 caractere, null o elimină — nu este returnată niciodată, doar passwordProtected), expiresAt (dată ISO, null pentru fără expirare), visibility și hideDownloadCount. Trimite doar câmpurile pe care vrei să le schimbi. DELETE /api/v1/files/{id} (permisiunea file:delete) elimină fișierul și pune în coadă pentru ștergere copiile lui de pe hosturi; adaugă ?keepMirrors=true ca să le păstrezi. Unele hosturi nu acceptă ștergerea, așa că o copie poate rămâne acolo.

bash, necesită jq; setează FILE_ID

API=https://api.mirroruploadx.com
H="x-api-key: $MUX_API_KEY"

# List your files, newest first (20 per page; pass ?cursor=<nextCursor> for more)
curl -sS "$API/api/v1/files?limit=20" -H "$H" | jq '.data.items[] | {id, name, mirrorCount, shareSlug}'

# One file, then every copy of it
curl -sS "$API/api/v1/files/$FILE_ID" -H "$H"
curl -sS "$API/api/v1/files/$FILE_ID/mirrors" -H "$H" | jq '.data.mirrors[] | {providerSlug, status, url}'

# Share settings: a password and an expiry date (null removes either)
curl -sS -X PATCH "$API/api/v1/files/$FILE_ID/share" -H "$H" -H "content-type: application/json" \
  -d '{"password":"correct-horse","expiresAt":"2026-12-31T23:59:59Z"}'

# Delete the file and its copies on hosts (?keepMirrors=true keeps the copies)
curl -sS -X DELETE "$API/api/v1/files/$FILE_ID" -H "$H"
DELETE /files/{id} → 200
{
  "success": true,
  "data": {
    "stagingDeleted": true,
    "mirrorsQueued": true,
    "mirrorsPurgeDeferred": false,
    "note": "File removed. Copies on providers are being deleted; some may remain on providers that do not support deletion."
  }
}

Webhookuri

Adaugă un endpoint pe pagina Webhookuri. URL-ul trebuie să folosească https://; secretul de semnare (whsec_…) este afișat o singură dată, la creare. Un endpoint fără evenimente selectate le primește pe toate.

EvenimentCând
upload.completedToate hosturile au acceptat fișierul, iar cel puțin minSuccess l-au acceptat — hosturile care au refuzat acest fișier (rejected) sau au fost anulate nu sunt luate în calcul
upload.partially_completedCel puțin minSuccess hosturi au acceptat fișierul, dar cel puțin un alt host a eșuat
upload.failedMai puțin de minSuccess hosturi au acceptat fișierul (minSuccess 0 contează ca 1)
upload.quarantinedScanarea antimalware a semnalat fișierul (doar când scanarea este activată)
provider.upload_succeededUn host a acceptat fișierul — trimis o dată per host
provider.upload_failedUn host a renunțat la fișier — trimis o dată per host
webhook.testAi apăsat Testează pe pagina Webhookuri

Fiecare livrare este un singur POST cu un corp JSON și headerele X-MUX-Event și X-MUX-Signature. Orice răspuns 2xx în 10 secunde contează ca livrat; redirecționările nu sunt urmate. O livrare eșuată (eroare de rețea, timeout, 408, 425, 429 sau 5xx) este reîncercată după 1, 5 și 30 de minute, cu același corp; celelalte coduri 4xx și redirecționările nu sunt reîncercate. Fiecare încercare conține X-MUX-Delivery-Attempt (1–4) și o semnătură nouă, așa că elimină duplicatele după corp. Ordinea livrărilor nu este garantată (un eveniment reîncercat poate sosi după unul mai nou); compară data și createdAt înainte de a acționa. Folosește GET /api/v1/mirror-tasks/{uploadJobId} ca să recuperezi starea. După 15 livrări consecutive a căror ultimă încercare a eșuat, sau după o oră de eșecuri fără niciun succes, endpointul este suspendat; reactivarea lui resetează contorul. O livrare webhook.test (butonul Testează) este trimisă o singură dată, cu X-MUX-Delivery-Attempt: 1, și nu este reîncercată niciodată.

Corp
{
  "event": "provider.upload_succeeded",
  "createdAt": "2026-09-25T12:00:00.000Z",
  "data": {
    "uploadJobId": "…",
    "fileId": "…",
    "provider": "gofile",
    "providerName": "Gofile",
    "status": "succeeded",
    "mirrorUrl": "https://…"
  }
}

Evenimentele upload.* conțin uploadJobId, fileId și status; provider.upload_failed conține errorCode în loc de mirrorUrl.

Verificarea semnăturii

Headerul arată ca t=1727265600,v1=5f2b…: t este momentul semnării în secunde Unix, v1 este HMAC-SHA256 hex al <t>.<raw body>, cu cheia secretă a endpointului tău. Calculează hashul pe octeții bruți exact așa cum au fost primiți, compară în timp constant și respinge marcajele temporale mai vechi de 5 minute.

Express

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((kv) => {
      const i = kv.indexOf('=');
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // too old: replay
  const expected = createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest();
  const got = Buffer.from(parts.v1, 'hex');
  return got.length === expected.length && timingSafeEqual(got, expected);
}

const app = express();
// Raw bytes, not parsed JSON: the signature covers the body exactly as sent.
app.post('/hooks/mirroruploadx', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('x-mux-signature') ?? '', process.env.MUX_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const { event, data } = JSON.parse(req.body);
  console.log(event, data.uploadJobId);
  res.sendStatus(204); // any 2xx counts as delivered
});
app.listen(3000);

Limite de rată

Limitele sunt contorizate per cheie API, nu per adresă IP. Fiecare răspuns de la un endpoint limitat conține X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset (secunde epoch). Depășirea returnează 429 RATE_LIMITED cu un header Retry-After — așteaptă atâtea secunde. Încărcarea bucăților are un buget larg; limitele stricte sunt la deschiderea sesiunilor și pornirea distribuirilor.

CategorieEndpointuriPer cheieInterval
Pornirea încărcărilorPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 minut
Încărcarea bucățilorPATCH /api/v1/upload-sessions/{id}/chunks6001 minut
Interogarea progresuluiGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 minut
Setările de distribuire ale unei încărcăriPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 minut
Pornirea distribuiriiPOST /api/v1/mirror-tasks/start301 minut
Încărcări de la URLPOST /api/v1/remote-uploads2010 minute
Citirea fișierelorGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 minut
Modificarea fișierelorPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 minut
Catalogul publicGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 minut

Acestea sunt valorile implicite. Operatorul le poate modifica, așa că headerele de mai sus sunt întotdeauna sursa de adevăr. Valorile exacte pentru cheile tale și cât ai consumat din fiecare în acest moment se află pe pagina Chei API. Cererile fără cheie sunt contorizate per adresă IP și primesc bugete mai mici pentru pornirea încărcărilor (10 în loc de 60), încărcarea bucăților (300 în loc de 600), interogarea progresului (300 în loc de 600), setările de distribuire ale unei încărcări (60 în loc de 300), pornirea distribuirii (10 în loc de 30), și același buget pentru încărcările de la URL și catalogul public. Citirea fișierelor și modificarea fișierelor necesită întotdeauna o cheie.

Erori

Răspunsurile reușite au forma { "success": true, "data": … }. Erorile folosesc o singură formă, alături de starea HTTP. code este stabil — ramifică logica după el; message este pentru oameni și se poate schimba. details este adăugat când există context suplimentar, retryable indică dacă repetarea aceleiași cereri poate ajuta, iar requestId ne ajută să-ți găsim cererea dacă contactezi asistența.

Eroare
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CodHTTPReîncerci?Semnificație
NO_TOKEN401NuNu a fost trimisă nicio cheie API
INVALID_API_KEY401NuCheia este greșită sau revocată
INSUFFICIENT_SCOPE403NuCheii îi lipsește permisiunea necesară pentru acest endpoint
API_KEY_NOT_ALLOWED403NuAcest endpoint nu poate fi folosit cu o cheie API
EMAIL_NOT_VERIFIED403NuVerifică mai întâi e-mailul contului; sesiunile deschise continuă să funcționeze
SESSION_REVOKED401NuSesiunea de autentificare a fost încheiată (resetarea sau schimbarea parolei, deconectare); autentifică-te din nou
ACCOUNT_INACTIVE403NuContul este suspendat sau programat pentru ștergere
ACCOUNT_DISABLED401 / 409NuContul a fost suspendat: 401 la verificarea cheii, 409 dacă s-a schimbat în timp ce cererea rula
ACCOUNT_PENDING_DELETION409NuContul a fost programat pentru ștergere în timp ce cererea rula; nu se pornește nimic nou
VALIDATION_ERROR400NuCorpul sau un parametru este invalid; vezi details
FILE_REJECTED400NuTipul sau mărimea fișierului nu sunt permise; details.reason spune care
TOO_MANY_MIRRORS400NuMai multe hosturi decât poate avea un fișier
NO_CONNECTED_PROVIDERS400NuFiecare host selectat necesită propriul tău cont și niciunul nu este conectat
PROVIDER_REJECTS_FILE400NuNiciun host selectat nu acceptă acest tip sau această mărime de fișier
NO_AVAILABLE_PROVIDERS400NuNiciunul dintre hosturile selectate nu acceptă încărcări acum; alege altele sau încearcă mai târziu. `details.waiting` listează hosturile doar puse pe pauză (de exemplu o limită zilnică, ridicată în 24 de ore): pentru ele o încercare ulterioară funcționează chiar dacă `retryable` este false
NO_VALID_PROVIDERS400NuNicio valoare din providerSlugs nu corespunde unui host activ; vezi GET /api/v1/providers
INVALID_JOB_STATE400NuJobul nu poate fi pornit în starea lui actuală
JOB_NOT_READY400NuFișierul nu are încă un job de distribuire
FILE_TOO_LARGE_FOR_UPLOAD400NuFișierul nu încape în 10 000 de bucăți de mărimea stabilită pentru sesiune; details.limitBytes
MISSING_OFFSET400NuO bucată a fost trimisă fără un header numeric upload-offset
RAW_BODY_REQUIRED400NuCorpul unei bucăți trebuie să fie format din octeți bruți, cu content-type application/offset+octet-stream
TOO_MANY_URLS400NuMai multe URL-uri într-o cerere remote-uploads decât este permis
FILE_NOT_FOUND404NuAcest fișier nu există în contul tău (sau a fost șters)
JOB_NOT_FOUND404NuAcest job de distribuire nu există în contul tău
SESSION_NOT_FOUND404NuAceastă sesiune de încărcare nu există în contul tău
SHARE_NOT_FOUND404NuFișierul nu are încă o pagină de partajare
QUOTA_EXCEEDED409NuO limită zilnică sau de încărcări simultane; details.retryAt spune când se eliberează
CHUNK_OFFSET_CONFLICT409Nuupload-offset nu corespunde octeților primiți; reia de la HEAD
CHUNK_TOO_SMALL409NuO bucată, alta decât ultima, are sub 5 MiB
CHUNK_TOO_MANY_PARTS409NuMai mult de 10 000 de bucăți; trimite bucăți mai mari
CHUNK_MISALIGNED409NuBucata nu este o felie întreagă de chunkSize care începe la un multiplu de chunkSize: obligatoriu pentru o bucată trimisă înainte și, dacă prima bucată a fost o felie întreagă de chunkSize, pentru fiecare bucată ulterioară (în ordine sau înainte); sau o bucată a fost trimisă înainte într-o sesiune care acceptă bucăți doar în ordine
CHUNK_OUT_OF_WINDOW409NuO bucată începe la mai mult de maxChunksAhead bucăți după uploadedBytes, sau după acesta înainte ca prima bucată să fi fost acceptată; trimite-o din nou după cele anterioare
CHUNK_EXCEEDS_DECLARED_SIZE409NuBucata depășește mărimea fișierului declarată la crearea sesiunii
CHUNK_EMPTY409NuBucata nu conține octeți
CHUNK_NOT_RECEIVABLE409NuSesiunea nu mai acceptă date (a fost finalizată, anulată sau a expirat); deschide una nouă
SESSION_EXPIRED409NuSesiunea de încărcare a expirat; deschide una nouă
SESSION_NOT_RECEIVABLE409NuSesiunea a fost anulată sau a expirat și nu mai acceptă modificări
SESSION_COMPLETED409NuÎncărcarea s-a terminat deja; șterge în schimb fișierul
UPLOAD_INCOMPLETE409NuNu au sosit toți octeții; trimite mai întâi bucățile rămase (details conține numărătorile)
IDEMPOTENCY_KEY_CONFLICT409NuAcest idempotencyKey este deja folosit de o altă încărcare; folosește o cheie unică pentru fiecare încărcare
SOURCE_GONE409NuCopia noastră a fișierului a fost deja ștearsă, așa că nu mai poate fi trimisă pe hosturile pe care nu a fost încercată; încarcă-l din nou pentru acestea. Copia noastră este ștearsă imediat ce un job de distribuire se termină (finalizat, finalizat parțial sau eșuat), iar o încărcare a cărei distribuire nu este pornită niciodată este ștearsă la 30 de minute după ce se termină (până la 72 de ore când planul ei de distribuire încă așteaptă hosturile; cu excepția încărcărilor de la URL). Un nou apel mirror-tasks/start pentru un job terminat, doar cu hosturi deja încercate, aplică doar setările de partajare (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409NuJobul a eșuat, a fost anulat sau se află într-o stare care nu mai permite distribuirea
SHARE_TAKEN_DOWN409NuPagina de partajare a fișierului a fost eliminată, așa că nu mai poate fi trimis pe alte hosturi
FINALIZING409DaO altă cerere asamblează fișierul; întreabă din nou peste câteva secunde
CONFLICT409DaColiziune cu o altă modificare în curs; reîncearcă aceeași cerere
TEMPORARILY_UNAVAILABLE503Da, după Retry-AfterServerul este ocupat acum; reîncearcă după intervalul Retry-After. details.reason "staging_full": spațiul de stocare temporar este plin, nu a fost acceptată nicio încărcare nouă (Retry-After aproximativ 10 minute); încărcările deja în curs continuă să funcționeze
PAYLOAD_TOO_LARGE413NuCorpul cererii (sau o bucată) este mai mare decât acceptă serverul
REMOTE_TOO_LARGEper URLNuÎntr-un rezultat remote-uploads: fișierul depășește limita pentru încărcarea de la URL
RATE_LIMITED429Da, după Retry-AfterPrea multe cereri pentru această categorie
INTERNAL_ERROR500DaEroare de server; detaliile sunt înregistrate, nu sunt returnate niciodată
MAINTENANCE503Da, după Retry-AfterÎncărcările noi sunt suspendate deocamdată; citirile continuă să funcționeze
UPLOADS_TEMPORARILY_UNAVAILABLE503Da, după Retry-AfterContorul nostru de încărcări nu a putut fi citit; nu a fost deschisă nicio sesiune
SHUTTING_DOWN503Da, după Retry-AfterServerul repornește (Retry-After 5 secunde); așteaptă și trimite din nou aceeași cerere — nu a fost procesat nimic

De ce a fost omis un host

Acestea nu sunt erori: apar în skipped[].reason al unui start reușit (și al distribution din răspunsul care completează fișierul). Celelalte hosturi primesc în continuare fișierul. Apelul eșuează doar când niciun host selectat nu îl poate prelua: PROVIDER_REJECTS_FILE (niciunul nu acceptă acest fișier), NO_CONNECTED_PROVIDERS (toate necesită propriul tău cont), NO_AVAILABLE_PROVIDERS (niciunul nu acceptă încărcări în acest moment) sau NO_VALID_PROVIDERS (niciun slug nu corespunde unui host activ).

MotivSemnificație
UNKNOWN_PROVIDERNu există niciun host cu acest slug — verifică ortografia în GET /api/v1/providers
PROVIDER_DISABLEDHostul este oprit sau în mentenanță în acest moment
ACCOUNT_REQUIREDHostul acceptă încărcări doar în propriul tău cont — conectează-l pe pagina Conexiuni
GUEST_UPLOAD_OFFHostul nu acceptă încărcări acum și nu poate fi conectat la un cont
DAILY_LIMIT_REACHEDLimita zilnică a hostului pentru încărcări fără cont este consumată deocamdată (până la 24 h) — conectează-ți propriul cont ca să poți încărca oricum
FILE_TOO_LARGEFișierul depășește limita de mărime a acestui host
MIME_NOT_ALLOWEDHostul nu acceptă acest tip de fișier
ALREADY_ATTEMPTEDAcest host a fost deja încercat pentru acest fișier, așa că nu i se mai trimite din nou

Referința API listează codurile pe care le poate returna fiecare endpoint.