Documentação da API

Crie um token em seu painel em Configurações → tokens de API. Envie-o em todas as solicitações no Authorization cabeçalho. Os tokens são mostrados uma vez na criação – armazene-os com segurança. Cada token atua em nome da sua conta e só vê seus próprios arquivos.

Authorization: Bearer f2s_YOUR_TOKEN

Os erros usam códigos de status HTTP padrão e retornam um corpo JSON com um error mensagem. Códigos comuns: 401 (token ausente/inválido), 403 (cota ou limite do plano), 404 (arquivo não encontrado), 409 (conflito — por exemplo, o arquivo já está em sua conta, consulte POST /v1/uploads), 422 (corpo da solicitação incorreto), 503 (nenhum servidor de armazenamento disponível).

{
  "error": "Invalid or revoked API token."
}

Retorna a conta do proprietário do token, o plano ativo e o uso atual de armazenamento.

curl https://api.fast2share.com/v1/user \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "id": 42,
  "email": "[email protected]",
  "display_name": "You",
  "plan": {
    "name": "premium-monthly",
    "max_file_size": 5368709120,
    "storage_quota": 107374182400
  },
  "usage": {
    "used_bytes": 2147483648,
    "file_count": 12,
    "remaining_bytes": 105226698752
  }
}

Lista seus arquivos concluídos, os mais recentes primeiro. Paginado por cursor: passe o retornado next_before como ?before= para a próxima página. Filtrar por nome com ?q=.

curl "https://api.fast2share.com/v1/files?before=0&q=report" \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "data": [
    {
      "uuid": "3f1c…-…-…",
      "name": "report.pdf",
      "size": 184320,
      "mime": "application/pdf",
      "sha256": "9f86d0…",
      "status": "completed",
      "downloads": 3,
      "share_url": "https://…/f/3f1c…",
      "created_at": "2026-07-01T10:00:00+00:00",
      "expires_at": null
    }
  ],
  "next_before": 1057
}

Encontra seus arquivos por nome. ?q= é obrigatório e corresponde a qualquer lugar no nome do arquivo, sem distinção entre maiúsculas e minúsculas. Mesma paginação de cursor da listagem (?before=), e a pesquisa abrange todas as pastas, a menos que você a defina com ?folder_id= (0 = arquivos localizados na raiz).

curl "https://api.fast2share.com/v1/files/search?q=invoice" \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "query": "invoice",
  "data": [
    {
      "uuid": "3f1c…-…-…",
      "name": "invoice-2026-07.pdf",
      "size": 184320,
      "mime": "application/pdf",
      "status": "completed",
      "share_url": "https://…/f/3f1c…",
      "created_at": "2026-07-01T10:00:00+00:00"
    }
  ],
  "next_before": null
}

Todas as pastas da sua conta, primeiro as pastas de nível superior. Use o id como o folder_id ao mover ou copiar um arquivo.

curl https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "data": [
    { "id": 12, "name": "Invoices", "parent_id": null, "created_at": "2026-06-02T09:12:00+00:00" },
    { "id": 19, "name": "2026",     "parent_id": 12,   "created_at": "2026-06-02T09:13:00+00:00" }
  ]
}

Cria uma pasta. name é obrigatório e deve ser exclusivo em sua conta (sem distinção entre maiúsculas e minúsculas) — um conflito responde 409. Passar parent_id para aninhá-lo: as pastas vão apenas um nível de profundidade, e um pai contém no máximo uma subpasta, então um pai que está aninhado (ou já tem um filho) responde 422.

curl -X POST https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoices","parent_id":null}'

{
  "id": 12,
  "name": "Invoices",
  "parent_id": null,
  "created_at": "2026-07-31T08:20:00+00:00"
}

Passo a passo de upload – os uploads são feitos em duas etapas porque os bytes vão direto para o servidor de armazenamento (através do retomável tu protocolo); eles nunca passam por esta API. Esta chamada valida seu plano/cota e retorna um endpoint tus mais um sinal upload_token.

1. POST /v1/uploads com o nome e tamanho do arquivo → retorna upload_url, upload_token e uuid (este ponto final).
2. Faça um upload do Tus para upload_url, adicionando os metadados token <upload_token>. Qualquer cliente tus funciona (por exemplo tus-js-client, tusc). Envie os bytes em pedaços (8 MB recomendados): uma única solicitação de tus contendo o arquivo inteiro é rejeitada com 413 pela CDN de armazenamento quando o corpo exceder aproximadamente 100 MB.
3. Enquete GET /v1/files/{uuid}/status até que informe completed, então use o retornado share_url.

Ignore a transferência com desduplicação (opcional). Se os mesmos bytes já estiverem armazenados, o arquivo poderá ser criado instantaneamente — nada será carregado:
• fingerprint = SHA-256 dos primeiros 8 MB concatenados com os últimos 8 MB (lê ≤16 MB; se o arquivo for ≤8 MB é simplesmente o SHA-256 de todo o arquivo, e entre 8 e 16 MB os dois intervalos o cobrem uma vez, sem sobreposição). Sempre envie isso quando você deseja desduplicação - é assim que a API sabe que você realmente possui o arquivo, de modo que os bytes pertencentes a outra conta nunca sejam compartilhados em uma soma de verificação simples.
• sha256 = arquivo completo SHA-256, hexadecimal. Envie junto com a impressão digital e a resposta é imediata: se sua conta já tem esse arquivo nada é criado e você obtém 409 com {"status":"exists","uuid":…,"share_url":…} apontando para sua cópia existente; se outra conta possuir os bytes, eles serão compartilhados com você instantaneamente: {"status":"completed","deduped":true,"share_url":…} - pronto, nada carregado.
• Para arquivos grandes, faça hash preguiçosamente: envie apenas o fingerprint. Uma resposta de {"status":"need_hash"} significa que existe uma possível correspondência - hash completo do arquivo e chamada POST /v1/uploads/{uuid}/confirm. Qualquer outra resposta é um ticket normal; carregue normalmente.
Omita ambos os campos para sempre fazer upload.

curl -X POST https://api.fast2share.com/v1/uploads \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","size":184320,"type":"application/pdf","fingerprint":"5b41e3…","sha256":"9f86d0…"}'

{
  "uuid": "3f1c…-…-…",
  "status": "pending",
  "upload_url": "https://storage1.example.com/files/",
  "upload_token": "eyJ1d….<sig>",
  "protocol": "tus",
  "metadata_key": "token"
}

// deduped instead — the bytes were already stored, nothing to upload:
{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}

Segunda etapa do fingerprint fluxo: chame isso somente depois POST /v1/uploads respondido {"status":"need_hash"}, com o arquivo completo sha256. A impressão digital e o tamanho são os que você enviou quando o upload foi criado — eles não são relidos nesta solicitação. Os mesmos três resultados acima: já em sua conta → 409 exists (nada armazenado); propriedade de outro lugar → completa imediatamente (deduped); caso contrário, a impressão digital simplesmente colidiu e você obterá o normal upload_url / upload_token ticket – carregue como na etapa 2 acima.

curl -X POST https://api.fast2share.com/v1/uploads/3f1c…-…-…/confirm \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"9f86d0…"}'

{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}

Retorna metadados de um único arquivo que você possui.

curl https://api.fast2share.com/v1/files/3f1c…-…-… \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "mime": "application/pdf",
  "sha256": "9f86d0…",
  "status": "completed",
  "downloads": 3,
  "share_url": "https://…/f/3f1c…",
  "created_at": "2026-07-01T10:00:00+00:00",
  "expires_at": null
}

Teste leve para o estado de um upload: pending, completed ou failed. Depois de concluído, ele também retorna o share_url.

curl https://api.fast2share.com/v1/files/3f1c…-…-…/status \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "size": 184320,
  "share_url": "https://…/f/3f1c…"
}

Cria um URL de download direto pronto para uso para um arquivo que você possui. O link transmite os bytes imediatamente com nenhuma sessão do navegador necessária (use-o em um script/curl) e expira após aproximadamente 5 minutos. Requer uma assinatura Premium ativa (administradores sempre permitidos).

curl https://api.fast2share.com/v1/files/3f1c…-…-…/download \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "download_url": "https://…/d/9xA2…",
  "expires_in": 300
}

Altera o nome de exibição de um arquivo que você possui. O link de compartilhamento (uuid) não muda, então os links que você já distribuiu continuam funcionando — apenas o nome mostrado na página de compartilhamento e enviado com o download muda. Separadores de caminho e caracteres de controle são removidos; o nome tem no máximo 512 caracteres.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/rename \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"invoice-july.pdf"}'

{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/3f1c…"
}

Arquiva um arquivo que você possui em uma de suas pastas. Enviar {"folder_id": 0} (ou omitir) para movê-lo de volta à raiz. A pasta deve ser sua, caso contrário 404.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/move \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12}'

{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "status": "completed",
  "share_url": "https://…/f/3f1c…",
  "folder_id": 12
}

Coloca um arquivo outra pessoa compartilhado com você em sua própria conta, com seu próprio link de compartilhamento – aqui {uuid} é o fonte slug de compartilhamento do arquivo, não um dos seus. Nenhum byte é transferido: a cópia aponta para o mesmo objeto armazenado, por isso é concluída instantaneamente e contabilizada em sua cota de armazenamento como qualquer outro arquivo.

A fonte deve ser pública, finalizada e seu proprietário deve permitir a cópia - caso contrário, você obterá 403. 409 significa que já é seu arquivo (ou já está em sua conta) e 403 também cobre "não resta armazenamento suficiente". Campos de corpo opcionais: folder_id, is_public (padrão verdadeiro) e free_download (padrão falso).

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/copy \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12,"is_public":true}'

{
  "uuid": "8b2e…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/8b2e…",
  "copied": true
}

Exclui de forma reversível um arquivo que você possui; ele para de ser baixado imediatamente e seus bytes são recuperados logo depois.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/delete \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{ "ok": true, "uuid": "3f1c…-…-…" }