Pular para o conteúdo

Documentação da API

Envie um arquivo uma vez, mande-o para os hosts de arquivos que você escolher e receba de volta um único link de compartilhamento — a partir do seu próprio código.

Atualizado em

Uma API REST versionada: envie um arquivo em partes, mande-o para os hosts que escolher, e todas as cópias ficam reunidas em uma página de compartilhamento com status ao vivo.

URL base
https://api.mirroruploadx.com/api/v1
Autenticação
x-api-key: mux_…
  1. 1Abra uma sessão

    POST /api/v1/upload-sessions

    filename + sizeBytes; receba sessionId e chunkSize

  2. 2Envie as partes

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

    bytes brutos, em ordem; a resposta que completa o arquivo traz fileId

  3. 3Distribua

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; depois consulte a tarefa

Crie uma chave na página Chaves de API. O passo a passo completo, com código, está em Enviar e distribuir.

Autenticação

Crie uma chave na página Chaves de API do seu painel. A chave completa (ela começa com mux_) é exibida só uma vez, então guarde-a na hora. Envie-a no cabeçalho x-api-key em todas as requisições; Authorization: Bearer mux_… é aceito da mesma forma, para clientes que só trabalham com bearer tokens.

As chaves têm escopo: uma chave só alcança os endpoints cobertos pelos seus escopos, e uma chamada com o escopo errado retorna 403 INSUFFICIENT_SCOPE com o escopo necessário na mensagem. Configurações da conta, gerenciamento de chaves e webhooks não podem ser acessados com uma chave de API de forma alguma (API_KEY_NOT_ALLOWED).

EscopoAlcança
upload:writeSessões de envio (criar, partes, concluir, cancelar), sua cota de envio, segurar ou alterar a distribuição automática de um envio (hold-distribution, distribution-intent), envios por URL remota, iniciar a distribuição
file:readListar arquivos, detalhes de arquivos, status dos espelhos e das tarefas
file:writeConfigurações de compartilhamento de um arquivo
file:deleteExcluir um arquivo e os espelhos dele

Endpoints

Tudo o que uma chave de API pode alcançar, além dos endpoints públicos que não precisam de chave. Quando a coluna de escopo lista dois escopos, qualquer um deles basta. Os esquemas de requisição e resposta de cada um estão na referência da API.

MétodoCaminhoEscopoO que faz
POST/api/v1/upload-sessionsupload:writeAbrir uma sessão de envio (opcionalmente com um plano de distribuição)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeEnviar a próxima parte de bytes
HEAD/api/v1/upload-sessions/{id}upload:writeOnde retomar: o cabeçalho Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readStatus da sessão: bytes recebidos, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readSeus limites de envio, uso e sessões não concluídas
POST/api/v1/upload-sessions/{id}/completeupload:writeConcluir um envio cuja resposta final se perdeu (seguro repetir)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeImpedir que uma distribuição adiada comece sozinha
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeSubstituir o plano de distribuição de um envio
DELETE/api/v1/upload-sessions/{id}upload:writeCancelar um envio não concluído e liberar a vaga dele
POST/api/v1/remote-uploadsupload:writeBuscar arquivos de URLs http(s) para a sua conta
POST/api/v1/mirror-tasks/startupload:writeMandar um arquivo para os hosts que você escolher
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readStatus da tarefa, cada host e o link de compartilhamento (shareTakenDown indica uma página removida)
GET/api/v1/filesfile:readListar seus arquivos (paginação por cursor, busca, filtros)
GET/api/v1/files/{id}file:readUm arquivo: tamanho, checksum, tarefa, configurações de compartilhamento, estatísticas
GET/api/v1/files/{id}/mirrorsfile:readTodas as cópias de um arquivo: host, link, saúde, cliques
PATCH/api/v1/files/{id}/sharefile:writeSenha, expiração e visibilidade do compartilhamento
DELETE/api/v1/files/{id}file:deleteExcluir um arquivo e (por padrão) as cópias dele nos hosts
GET/api/v1/platformnenhum (público)Limites atuais: maior arquivo, hosts por arquivo, tetos de envio por URL
GET/api/v1/providersnenhum (público)O catálogo de hosts, com os slugs que você envia em providerSlugs
GET/api/v1/providers/statusnenhum (público)Sucesso de envio medido por host
GET/api/v1/stats/publicnenhum (público)Totais da plataforma nos últimos 30 dias: arquivos, espelhos no ar, taxa de sucesso

Enviar um arquivo e distribuí-lo

  1. Abra uma sessão com POST /api/v1/upload-sessions. filename e sizeBytes (o tamanho exato em bytes) são obrigatórios; mimeType e uma idempotencyKey UUID são opcionais — repetir uma requisição com a mesma chave retorna a sessão existente em vez de abrir uma segunda. A resposta traz data.sessionId (não id) e data.chunkSize.
  2. Envie os bytes com PATCH /api/v1/upload-sessions/{id}/chunks: bytes brutos, content type application/offset+octet-stream e a posição inicial da parte no cabeçalho upload-offset. As partes vão em ordem, ou até maxChunksAhead partes adiante; enviando em ordem, use data.uploadedBytes de cada resposta como o próximo offset. Envie partes de chunkSize bytes; toda parte, exceto a última, deve ter pelo menos 5 MiB, e um envio pode ter no máximo 10 000 partes. A resposta que completa o arquivo traz data.fileId. Para ganhar velocidade, você pode manter 2–3 partes do mesmo arquivo em trânsito. Envie a primeira parte sozinha; a resposta dela informa o data.maxChunksAhead real (4 quando a primeira parte foi uma fatia inteira de chunkSize, 0 = só em ordem). Se a primeira parte foi uma fatia inteira de chunkSize, todas as partes seguintes também precisam ser (em ordem ou adiante): começam em um múltiplo de chunkSize e têm exatamente chunkSize bytes (a última: o restante do arquivo). Uma parte enviada à frente de uploadedBytes precisa ser uma fatia assim e começar no máximo data.maxChunksAhead partes adiante; caso contrário, recebe 409 CHUNK_MISALIGNED ou 409 CHUNK_OUT_OF_WINDOW. uploadedBytes conta só os bytes recebidos sem lacuna, e a parte que completar o arquivo, seja ela qual for, recebe a resposta com fileId. Reenviar uma parte que já chegou é um sucesso inofensivo.
  3. Distribua com POST /api/v1/mirror-tasks/start: fileId e providerSlugs são obrigatórios (os slugs vêm de GET /api/v1/providers). Opcionais: minSuccess (padrão 1 — quantos hosts precisam aceitar o arquivo para a tarefa não falhar; ela só fica completed quando todos os hosts também o aceitaram, caso contrário partially_completed. Hosts que recusam este tipo de arquivo não são contados), sharePassword, expiresInDays ou expiresAt. A resposta traz uploadJobId, taskCount, shareSlug, alreadyStarted e skipped[] — um host que não pode aceitar este arquivo é ignorado, não conta como falha, então leia skipped[] (os motivos estão listados abaixo). No momento, um arquivo pode ir para no máximo 50 hosts.
  4. Acompanhe a conclusão com GET /api/v1/mirror-tasks/{uploadJobId} a cada poucos segundos, até data.terminal ser true. A resposta lista cada host em tasks[] (providerSlug, status, mirrorUrl, errorCode) e o link de compartilhamento em data.shareUrl. data.shareTakenDown é true quando essa página de compartilhamento foi removida e não abre mais.

O maior arquivo aceito no momento é de 5,00 GB.

bash, requer 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

Exemplos de respostas

Abrir uma sessão responde 201. Cada parte, exceto a última, responde { uploadedBytes, completed: false, expiresAt }; a última traz o arquivo. distribution só aparece quando você passou um plano ao abrir a sessão (veja abaixo).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (completa o arquivo) → 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
      }
    ]
  }
}

Um primeiro start bem-sucedido responde 202; chamá-lo de novo para uma tarefa que já está em andamento responde 200 com alreadyStarted: true. Quando o link de um host é mantido privado por política, mirrorUrl é null e mirrorHidden é true — a página de compartilhamento ainda o lista.

Pule a segunda chamada

Passe distribution ao abrir a sessão e o servidor começa a distribuir assim que o arquivo estiver completo. Confira data.distribution na resposta que completa o arquivo: started: true significa que a tarefa está na fila (uploadJobId, shareSlug). Com started: false e deferred: true, nada foi colocado na fila ainda, de propósito — veja abaixo. Com started: false e sem deferred, o envio deu certo, mas a distribuição não pôde começar (error diz por quê): chame POST /api/v1/mirror-tasks/start com o fileId. Um error junto com deferred: true significa uma falha temporária (por exemplo, todos os hosts estão ocupados ou em manutenção): não chame start nem envie o arquivo de novo — o próprio servidor vai tentar iniciar a distribuição de novo a partir de autoStartAt (até 5 tentativas). Chame hold-distribution para impedir isso.

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": "…" } }

Adicione deferred: true a distribution para ter um período de carência: a resposta final é { started: false, deferred: true, autoStartAt } e o próprio servidor inicia a distribuição em autoStartAt (cerca de 2 minutos depois), a menos que você chame start antes. Para impedir o início automático, chame POST /api/v1/upload-sessions/{id}/hold-distribution (sem corpo; autoStartAt passa a ser null e você mesmo inicia). Para alterar o plano, chame PUT /api/v1/upload-sessions/{id}/distribution-intent com os mesmos campos de distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): isso substitui o plano e remove uma retenção, e, se o envio já terminou, o início automático passa para pelo menos 2 minutos após a chamada. Se a distribuição já começou, ambos respondem 200 e distribution-intent informa alreadyStarted: true.

Inicie em até 30 minutos. Quando um envio termina e nenhuma distribuição é iniciada, nossa cópia do arquivo é removida após 30 minutos (com um plano de distribuição ainda aguardando hosts ficarem disponíveis, após no máximo 72 horas; envios por URL remota não são afetados). Depois disso, start e distribution-intent respondem 409 SOURCE_GONE e o arquivo precisa ser enviado de novo.

Se a resposta final se perder

Chame GET /api/v1/upload-sessions/{id}: um fileId significa que o arquivo existe; finalizable: true significa que todos os bytes chegaram e que POST /api/v1/upload-sessions/{id}/complete o conclui. Essa chamada é segura para repetir e nunca cria um segundo arquivo. Um offset divergente recebe 409 CHUNK_OFFSET_CONFLICT — envie HEAD na sessão e retome a partir do cabeçalho Upload-Offset dela. Chamar start de novo para uma tarefa em andamento não é erro: você recebe 200 com alreadyStarted: true.

Enviar a partir de uma URL

POST /api/v1/remote-uploads recebe { "urls": [...] } e busca cada arquivo para você (escopo upload:write). Só links http e https são buscados, endereços de redes privadas são recusados e só um número limitado de redirecionamentos é seguido. Uma requisição leva no máximo 10 URLs (informado por GET /api/v1/platform); divida listas maiores.

O limite de tamanho por arquivo depende da origem. Quando ela informa o tamanho do arquivo, cada arquivo pode ter até 5,00 GB (limits.remoteUploadPassthroughMaxBytes); quando não informa, até 100,0 MB (limits.remoteUploadMaxBytes). O nome do arquivo vem do cabeçalho Content-Disposition da origem, quando ela o envia; um nome sem extensão recebe uma com base no tipo do arquivo.

A requisição aguarda enquanto os arquivos são baixados. Se a conexão cair antes, o arquivo ainda chega à sua conta — encontre-o com GET /api/v1/files. Cada fileId é então distribuído com POST /api/v1/mirror-tasks/start, como acima.

Quando o armazenamento temporário está cheio, a requisição inteira recebe 503 TEMPORARILY_UNAVAILABLE com details.reason: "staging_full" e um cabeçalho Retry-After. Se só uma URL não couber, essa entrada em results[] tem ok: false e o mesmo código; um resultado por URL não tem cabeçalho, então a espera em segundos fica em 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.

Gerenciar arquivos

Seus arquivos ficam na sua conta depois do envio. Liste-os com GET /api/v1/files (limit até 100; passe o nextCursor da resposta como cursor para a próxima página, q busca pelo nome). GET /api/v1/files/{id} retorna um arquivo com a tarefa, as configurações de compartilhamento e as estatísticas de visualização; GET /api/v1/files/{id}/mirrors lista cada cópia com o link, a saúde e os cliques.

PATCH /api/v1/files/{id}/share (escopo file:write) altera a página de compartilhamento: password (4–128 caracteres, null remove — ela nunca é retornada, só passwordProtected), expiresAt (data ISO, null para sem expiração), visibility e hideDownloadCount. Envie só os campos que quer alterar. DELETE /api/v1/files/{id} (escopo file:delete) remove o arquivo e coloca na fila a exclusão das cópias dele nos hosts; adicione ?keepMirrors=true para mantê-las. Alguns hosts não suportam exclusão, então uma cópia pode continuar lá.

bash, requer jq; defina 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."
  }
}

Webhooks

Adicione um endpoint na página Webhooks. A URL deve usar https://; o segredo de assinatura dela (whsec_…) é exibido uma vez, na criação. Um endpoint sem eventos selecionados recebe todos eles.

EventoQuando
upload.completedTodos os hosts aceitaram o arquivo, e pelo menos minSuccess aceitaram — hosts que recusaram este arquivo (rejected) ou foram cancelados não são contados
upload.partially_completedPelo menos minSuccess hosts aceitaram o arquivo, mas pelo menos um outro host falhou
upload.failedMenos de minSuccess hosts aceitaram o arquivo (minSuccess 0 conta como 1)
upload.quarantinedA verificação de malware sinalizou o arquivo (só quando a verificação está ativada)
provider.upload_succeededUm host aceitou o arquivo — enviado uma vez por host
provider.upload_failedUm host desistiu do arquivo — enviado uma vez por host
webhook.testVocê clicou em Testar na página Webhooks

Cada entrega é um POST com corpo JSON e os cabeçalhos X-MUX-Event e X-MUX-Signature. Qualquer resposta 2xx em até 10 segundos conta como entregue; redirecionamentos não são seguidos. Uma entrega com falha (erro de rede, tempo esgotado, 408, 425, 429 ou 5xx) é repetida após 1, 5 e 30 minutos com o mesmo corpo; outros 4xx e redirecionamentos não. Cada tentativa traz X-MUX-Delivery-Attempt (1–4) e uma assinatura nova, então elimine duplicatas pelo corpo. A ordem de entrega não é garantida (um evento repetido pode chegar depois de um mais novo); compare data e createdAt antes de agir. Use GET /api/v1/mirror-tasks/{uploadJobId} para se atualizar. Após 15 entregas seguidas cuja última tentativa falhou, ou uma hora de falhas sem nenhum sucesso, o endpoint é pausado; reativá-lo zera a contagem. Uma entrega webhook.test (o botão Testar) é enviada uma vez, com X-MUX-Delivery-Attempt: 1, e nunca é repetida.

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

Os eventos upload.* trazem uploadJobId, fileId e status; provider.upload_failed traz errorCode em vez de mirrorUrl.

Verificar a assinatura

O cabeçalho tem o formato t=1727265600,v1=5f2b…: t é o momento da assinatura em segundos Unix, v1 é o HMAC-SHA256 em hexadecimal de <t>.<raw body>, com o segredo do seu endpoint como chave. Calcule o hash dos bytes brutos exatamente como recebidos, compare em tempo constante e rejeite timestamps com mais de 5 minutos.

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);

Limites de requisições

Os limites são contados por chave de API, não por endereço IP. Toda resposta de um endpoint limitado traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos epoch). Ultrapassar o limite retorna 429 RATE_LIMITED com um cabeçalho Retry-After — aguarde esse número de segundos. O envio de partes tem uma cota ampla; os limites estreitos ficam na abertura de sessões e no início de distribuições.

GrupoEndpointsPor chaveJanela
Iniciar enviosPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 minuto
Enviar partesPATCH /api/v1/upload-sessions/{id}/chunks6001 minuto
Consultar o progressoGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 minuto
Configurações de distribuição de um envioPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 minuto
Iniciar a distribuiçãoPOST /api/v1/mirror-tasks/start301 minuto
Envios remotos (URL)POST /api/v1/remote-uploads2010 minutos
Ler arquivosGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 minuto
Alterar arquivosPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 minuto
Catálogo públicoGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 minuto

Estes são os números padrão. O operador pode alterá-los, então os cabeçalhos acima são sempre a fonte da verdade. Os números exatos das suas chaves, e quanto de cada um você já usou agora, estão na página Chaves de API. Requisições sem chave são contadas por endereço IP e recebem cotas menores para iniciar envios (10 em vez de 60), enviar partes (300 em vez de 600), consultar o progresso (300 em vez de 600), configurações de distribuição de um envio (60 em vez de 300), iniciar a distribuição (10 em vez de 30), e a mesma cota para envios remotos (URL) e catálogo público. Ler arquivos e alterar arquivos sempre exigem uma chave.

Erros

Respostas de sucesso são { "success": true, "data": … }. Os erros usam um único formato, junto com o status HTTP. code é estável — use-o nas suas condições; message é para pessoas e pode mudar. details é adicionado quando há mais contexto, retryable diz se repetir a mesma requisição pode ajudar, e requestId nos ajuda a encontrar a sua requisição se você falar com o suporte.

Erro
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CódigoHTTPRepetir?Significado
NO_TOKEN401NãoNenhuma chave de API foi enviada
INVALID_API_KEY401NãoA chave está errada ou foi revogada
INSUFFICIENT_SCOPE403NãoA chave não tem o escopo que este endpoint exige
API_KEY_NOT_ALLOWED403NãoEste endpoint não pode ser usado com uma chave de API
EMAIL_NOT_VERIFIED403NãoConfirme primeiro o e-mail da conta; as sessões abertas continuam funcionando
SESSION_REVOKED401NãoA sessão de login foi encerrada (redefinição ou troca de senha, saída da conta); entre de novo
ACCOUNT_INACTIVE403NãoA conta está suspensa ou agendada para exclusão
ACCOUNT_DISABLED401 / 409NãoA conta foi suspensa: 401 na verificação da chave, 409 se isso mudou durante a requisição
ACCOUNT_PENDING_DELETION409NãoA conta foi agendada para exclusão durante a requisição; nada novo é iniciado
VALIDATION_ERROR400NãoO corpo ou um parâmetro é inválido; veja details
FILE_REJECTED400NãoO tipo ou o tamanho do arquivo não é permitido; details.reason diz qual
TOO_MANY_MIRRORS400NãoMais hosts do que um arquivo pode ter
NO_CONNECTED_PROVIDERS400NãoTodos os hosts selecionados precisam da sua própria conta e nenhum está conectado
PROVIDER_REJECTS_FILE400NãoNenhum host selecionado aceita este tipo ou tamanho de arquivo
NO_AVAILABLE_PROVIDERS400NãoNenhum dos hosts selecionados está aceitando envios agora; escolha outros ou tente mais tarde. `details.waiting` lista os hosts apenas pausados (por exemplo, um limite diário, liberado em até 24 horas): para eles, tentar mais tarde funciona mesmo com `retryable` false
NO_VALID_PROVIDERS400NãoNenhum valor de providerSlugs corresponde a um host ativo; veja GET /api/v1/providers
INVALID_JOB_STATE400NãoA tarefa não pode ser iniciada no estado atual
JOB_NOT_READY400NãoO arquivo ainda não tem tarefa de distribuição
FILE_TOO_LARGE_FOR_UPLOAD400NãoO arquivo não cabe em 10 000 partes do chunkSize da sessão; details.limitBytes
MISSING_OFFSET400NãoUma parte foi enviada sem um cabeçalho upload-offset numérico
RAW_BODY_REQUIRED400NãoO corpo de uma parte deve ser bytes brutos com content-type application/offset+octet-stream
TOO_MANY_URLS400NãoMais URLs em uma requisição remote-uploads do que o permitido
FILE_NOT_FOUND404NãoEsse arquivo não existe na sua conta (ou foi excluído)
JOB_NOT_FOUND404NãoEssa tarefa de distribuição não existe na sua conta
SESSION_NOT_FOUND404NãoEssa sessão de envio não existe na sua conta
SHARE_NOT_FOUND404NãoO arquivo ainda não tem página de compartilhamento
QUOTA_EXCEEDED409NãoUm limite diário ou de envios simultâneos; details.retryAt diz quando ele é liberado
CHUNK_OFFSET_CONFLICT409Nãoupload-offset não corresponde aos bytes recebidos; retome a partir do HEAD
CHUNK_TOO_SMALL409NãoUma parte que não é a última tem menos de 5 MiB
CHUNK_TOO_MANY_PARTS409NãoMais de 10 000 partes; envie partes maiores
CHUNK_MISALIGNED409NãoA parte não é uma fatia inteira de chunkSize começando em um múltiplo de chunkSize: isso é exigido para uma parte enviada adiante e, se a primeira parte foi uma fatia inteira de chunkSize, também para todas as partes seguintes (em ordem ou adiante); ou uma parte foi enviada adiante em uma sessão que só aceita partes em ordem
CHUNK_OUT_OF_WINDOW409NãoUma parte começa mais de maxChunksAhead partes além de uploadedBytes, ou além dele antes de a primeira parte ser aceita; envie-a de novo depois das anteriores
CHUNK_EXCEEDS_DECLARED_SIZE409NãoA parte ultrapassa o tamanho de arquivo declarado na criação da sessão
CHUNK_EMPTY409NãoA parte não tem bytes
CHUNK_NOT_RECEIVABLE409NãoA sessão não aceita mais dados (foi concluída, cancelada ou expirou); abra uma nova
SESSION_EXPIRED409NãoA sessão de envio expirou; abra uma nova
SESSION_NOT_RECEIVABLE409NãoA sessão foi cancelada ou expirou e não aceita mais alterações
SESSION_COMPLETED409NãoO envio já terminou; exclua o arquivo em vez disso
UPLOAD_INCOMPLETE409NãoNem todos os bytes chegaram; envie primeiro as partes restantes (details traz as contagens)
IDEMPOTENCY_KEY_CONFLICT409NãoEsta idempotencyKey já é usada por outro envio; use uma chave única por envio
SOURCE_GONE409NãoNossa cópia do arquivo já foi removida, então ele não pode ser mandado para hosts em que ainda não foi tentado; envie-o de novo para esses. Nossa cópia é removida assim que uma tarefa de distribuição termina (concluída, concluída em parte ou com falha), e um envio cuja distribuição nunca é iniciada é removido 30 minutos após terminar (até 72 horas quando o plano de distribuição ainda aguarda hosts; exceto envios por URL remota). Chamar mirror-tasks/start de novo para uma tarefa concluída só com hosts já tentados apenas aplica as configurações de compartilhamento (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409NãoA tarefa falhou, foi cancelada ou está em um estado que não permite mais distribuição
SHARE_TAKEN_DOWN409NãoA página de compartilhamento do arquivo foi removida, então ele não pode ser mandado para mais hosts
FINALIZING409SimOutra requisição está montando o arquivo; pergunte de novo em alguns segundos
CONFLICT409SimColidiu com outra alteração em andamento; repita a mesma requisição
TEMPORARILY_UNAVAILABLE503Sim, após Retry-AfterO servidor está ocupado agora; tente de novo após o intervalo de Retry-After. details.reason "staging_full": o armazenamento temporário está cheio e nenhum envio novo foi aceito (Retry-After de cerca de 10 minutos); envios já em andamento continuam funcionando
PAYLOAD_TOO_LARGE413NãoO corpo da requisição (ou uma parte) é maior do que o servidor aceita
REMOTE_TOO_LARGEpor URLNãoEm um resultado de remote-uploads: o arquivo passa do limite de envio por URL
RATE_LIMITED429Sim, após Retry-AfterRequisições demais para este grupo
INTERNAL_ERROR500SimErro no servidor; os detalhes são registrados, nunca retornados
MAINTENANCE503Sim, após Retry-AfterNovos envios estão pausados por enquanto; leituras continuam funcionando
UPLOADS_TEMPORARILY_UNAVAILABLE503Sim, após Retry-AfterNão foi possível ler nosso contador de envios; nenhuma sessão foi aberta
SHUTTING_DOWN503Sim, após Retry-AfterO servidor está reiniciando (Retry-After de 5 segundos); aguarde e envie a mesma requisição de novo — nada foi processado

Por que um host foi ignorado

Isto não são erros: chegam em skipped[].reason de um start bem-sucedido (e de distribution na resposta que completa o arquivo). Os outros hosts recebem o arquivo normalmente. A chamada só falha quando nenhum host selecionado pode aceitá-lo: PROVIDER_REJECTS_FILE (nenhum aceita este arquivo), NO_CONNECTED_PROVIDERS (todos precisam da sua própria conta), NO_AVAILABLE_PROVIDERS (nenhum está aceitando envios agora) ou NO_VALID_PROVIDERS (nenhum slug corresponde a um host ativo).

MotivoSignificado
UNKNOWN_PROVIDERNão existe host com este slug — confira a grafia em GET /api/v1/providers
PROVIDER_DISABLEDO host está desativado ou em manutenção agora
ACCOUNT_REQUIREDO host só aceita envios para a sua própria conta — conecte-o na página Conexões
GUEST_UPLOAD_OFFO host não está aceitando envios agora e não pode ser conectado a uma conta
DAILY_LIMIT_REACHEDO limite diário do host para envios sem conta se esgotou por enquanto (até 24 h) — conecte sua própria conta para enviar mesmo assim
FILE_TOO_LARGEO arquivo passa do limite de tamanho deste host
MIME_NOT_ALLOWEDO host não aceita este tipo de arquivo
ALREADY_ATTEMPTEDEste host já foi tentado para este arquivo, então ele não é enviado de novo para lá

A referência da API lista os códigos que cada endpoint pode retornar.