Referência da API

Visão geral

A API do Uploadex permite que você envie arquivos programaticamente, liste-os e atualize metadados em nome do dono da chave de API. Todo endpoint é um recurso REST: JSON (ou multipart para uploads binários) entrando, JSON saindo, apenas HTTPS.

URL base: https://uploadex.net/api/v1
Autenticação: Tokens Bearer no header Authorization
Transporte: Apenas HTTPS · TLS 1.2 ou 1.3
Codificação: JSON UTF-8 · multipart/form-data para uploads
Datas: ISO 8601 em UTC · 2026-04-21T08:12:04Z

Autenticação

Toda requisição deve incluir um header Authorization com um token Bearer. Crie e faça rotação de chaves no seu painel de desenvolvedor.

Authorization: Bearer ux_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

As chaves começam com ux_live_. Elas são mostradas exatamente uma vez na criação — guarde-as em um gerenciador de segredos. As chaves podem ser escopadas para ações específicas (files:read, files:write, upload ou *) e configuradas para expirar em uma data futura.

O acesso à API exige um plano com API habilitada. Se a conta fizer downgrade para um plano sem API, as chaves existentes param de funcionar até a conta voltar a fazer upgrade. Revogue chaves vazadas imediatamente pelo painel de desenvolvedor.

Início rápido

Busque suas informações de conta para confirmar que a chave funciona.

# Get your account info
curl https://uploadex.net/api/v1/account \
  -H "Authorization: Bearer $UX_API_KEY"

Resposta · 200 OK

{
  "data": {
    "id":               "clxxxxxxxxxxxxxxxxxxxxxx",
    "email":            "[email protected]",
    "name":             "Your Name",
    "plan":             "PRO",
    "balance":          0,
    "totalEarnings":    0,
    "storageUsed":      52428800,
    "storageLimit":     53687091200,
    "storageFormatted": "50 MB / 50 GB",
    "fileCount":        3,
    "createdAt":        "2026-04-01T09:21:00.000Z"
  }
}

Limites de plano

Limites de upload e storage dependem do plano e podem mudar quando a conta faz upgrade ou downgrade. Limites para planos que incluem acesso à API:

Plano	Tamanho máx. do arquivo	Armazenamento
Pro	10 GB	100 GB
Business	50 GB	1 TB
Business Plus	100 GB	5 TB

Limites de taxa

Os limites de taxa protegem o serviço contra tráfego descontrolado. Exceder um limite retorna 429 Too Many Requests.

Escopo	Limite	Janela	Sujeito
Iniciar upload	30	1 min	por chave de API
Download	60	1 min	por IP
Login	10	15 min	por IP
Registro	5	1h	por IP

Erros

As respostas de erro usam códigos HTTP padrão e um corpo JSON consistente.

{ "error": "Invalid or missing API key" }

Status	Significado
400	O corpo da requisição estava malformado ou falhou na validação.
401	Chave de API ausente ou inválida.
403	A chave não tem um escopo obrigatório (ex: files:write).
404	O recurso não existe ou não pertence ao dono da chave.
413	O arquivo excede o limite de tamanho do plano da conta.
429	Limite de taxa excedido. Diminua e tente novamente.
500	Erro interno. Verifique a página de status antes de tentar novamente.

Paginação

Os endpoints de listagem usam paginação por página. Passe page (começando em 1) e limit (máx 100) como parâmetros de query.

GET /api/v1/files?page=1&limit=50

Conta

GET/api/v1/account

Retorna informações da conta, plano, uso de storage e contagem de arquivos.

Escopo: nenhum escopo necessário além de uma chave válida.

Upload

POST/api/v1/upload

Inicia um upload multipart. Retorna URLs pré-assinadas que o cliente usa para fazer PUT dos chunks no object storage R2.

Campo	Tipo	Descrição
filename	string · required	Nome do arquivo, incluindo extensão (máx 255 chars).
size	integer · required	Tamanho total do arquivo em bytes.
contentType	string · required	Tipo MIME (máx 200 chars).

Escopo: upload. Retorna 413 se size exceder o limite do plano da conta.

Arquivos

GET/api/v1/files

Lista arquivos do dono da chave. Suporta page, limit (máx 100), status.

GET/api/v1/files/:id

Recupera um único arquivo por ID.

PATCH/api/v1/files/:id

Atualiza displayName, description, tags ou visibility.

DELETE/api/v1/files/:id

Deleta o arquivo e recupera a cota de storage.

{
  "data": {
    "id":            "clxxxxxxxxxxxxxxxxxxxxxx",
    "slug":          "9nK2xA",
    "filename":      "demo.mp4",
    "size":          881975296,
    "sizeFormatted": "841.1 MB",
    "mimeType":      "video/mp4",
    "status":        "READY",
    "scanStatus":    "CLEAN",
    "downloads":     128,
    "views":         412,
    "tags":          ["demo"],
    "visibility":    "PUBLIC",
    "adsEnabled":    true,
    "createdAt":     "2026-04-21T08:12:04.000Z",
    "updatedAt":     "2026-04-21T08:12:04.000Z"
  }
}

Escopos: GET requer files:read; PATCH/DELETE requerem files:write.

API do Uploadex referência.