Tài liệu API

Tạo mã thông báo trong bảng điều khiển của bạn bên dưới Cài đặt → Mã thông báo API. Gửi nó theo mọi yêu cầu trong Authorization tiêu đề. Mã thông báo được hiển thị một lần khi tạo - lưu trữ chúng một cách an toàn. Mỗi mã thông báo hoạt động thay mặt cho tài khoản của bạn và chỉ nhìn thấy các tệp của riêng bạn.

Authorization: Bearer f2s_YOUR_TOKEN

Lỗi sử dụng mã trạng thái HTTP tiêu chuẩn và trả về phần nội dung JSON có phần mở rộng error tin nhắn. Các mã phổ biến: 401 (mã thông báo bị thiếu/không hợp lệ), 403 (hạn ngạch hoặc giới hạn kế hoạch), 404 (không tìm thấy tập tin), 409 (xung đột - ví dụ: tệp đã có trong tài khoản của bạn, hãy xem POST /v1/uploads), 422 (nội dung yêu cầu xấu), 503 (không có máy chủ lưu trữ).

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

Trả về tài khoản của chủ sở hữu mã thông báo, gói đang hoạt động và mức sử dụng bộ nhớ hiện tại.

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
  }
}

Liệt kê các tập tin đã hoàn thành của bạn, mới nhất đầu tiên. Phân trang bằng con trỏ: chuyển kết quả trả về next_before BẰNG ?before= cho trang tiếp theo. Lọc theo tên với ?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
}

Tìm tập tin của bạn theo tên. ?q= là bắt buộc và khớp với bất kỳ vị trí nào trong tên tệp, không phân biệt chữ hoa chữ thường. Phân trang con trỏ giống như danh sách (?before=) và tìm kiếm trải rộng trên mọi thư mục trừ khi bạn xác định phạm vi của nó với ?folder_id= (0 = các tập tin nằm ở thư mục gốc).

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
}

Mọi thư mục trong tài khoản của bạn, trước tiên là các thư mục cấp cao nhất. Sử dụng id như folder_id khi di chuyển hoặc sao chép một tập tin.

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" }
  ]
}

Tạo một thư mục. name là bắt buộc và phải là duy nhất trên tài khoản của bạn (không phân biệt chữ hoa chữ thường) — một câu trả lời xung đột 409. Vượt qua parent_id để lồng nó: các thư mục đi chỉ sâu một cấp độvà thư mục gốc chứa tối đa một thư mục con, do đó thư mục gốc được lồng vào nhau (hoặc đã có thư mục con) sẽ trả lời 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"
}

Hướng dẫn tải lên - tải lên gồm hai bước bởi vì byte đi thẳng đến máy chủ lưu trữ (thông qua sơ yếu lý lịch tus giao thức); họ không bao giờ vượt qua API này. Lệnh gọi này xác nhận gói/hạn ngạch của bạn và trả về điểm cuối tus cộng với một upload_token.

1. POST /v1/uploads với tên tệp và kích thước → trả về upload_url, upload_token Và uuid (điểm cuối này).
2. Thực hiện tus upload lên upload_url, thêm siêu dữ liệu token <upload_token>. Bất kỳ ứng dụng khách nào của tus đều hoạt động (ví dụ: tus-js-client, tusc). Gửi byte theo khối (Khuyến nghị 8 MB): một yêu cầu tus chứa toàn bộ tệp sẽ bị từ chối với 413 bởi CDN lưu trữ khi nội dung vượt quá ~100 MB.
3. Thăm dò ý kiến GET /v1/files/{uuid}/status cho đến khi nó báo cáo completed, sau đó sử dụng trả lại share_url.

Bỏ qua quá trình chuyển bằng tính năng khấu trừ (tùy chọn). Nếu các byte tương tự đã được lưu trữ, tệp có thể được tạo ngay lập tức — không có gì được tải lên:
• fingerprint = SHA-256 của 8 MB đầu tiên được nối với 8 MB cuối cùng (đọc ≤16 MB; nếu tệp là ≤8 MB thì đó chỉ đơn giản là SHA-256 của toàn bộ tệp và từ 8 đến 16 MB, hai phạm vi bao phủ tệp đó một lần mà không bị chồng chéo). Luôn gửi cái này khi bạn muốn khấu trừ - đó là cách API biết bạn thực sự giữ tệp, do đó byte thuộc sở hữu của tài khoản khác không bao giờ được chia sẻ trên tổng kiểm tra trần.
• sha256 = tệp đầy đủ SHA-256, hex. Gửi nó cùng với dấu vân tay và câu trả lời là ngay lập tức: nếu tài khoản của bạn đã có tập tin đó không có gì được tạo ra và bạn nhận được 409 với {"status":"exists","uuid":…,"share_url":…} chỉ vào bản sao hiện có của bạn; nếu tài khoản khác sở hữu byte thì chúng sẽ được chia sẻ ngay lập tức với bạn: {"status":"completed","deduped":true,"share_url":…} - xong, không có gì được tải lên.
• Thay vào đó, đối với các tệp lớn được băm một cách lười biếng: chỉ gửi fingerprint. Một câu trả lời của {"status":"need_hash"} có nghĩa là có thể tồn tại sự trùng khớp - băm toàn bộ tệp và gọi POST /v1/uploads/{uuid}/confirm. Bất kỳ câu trả lời nào khác đều là một vé bình thường; tải lên như bình thường.
Bỏ qua cả hai trường để luôn tải lên.

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

Bước thứ hai của fingerprint flow: chỉ gọi cái này sau POST /v1/uploads đã trả lời {"status":"need_hash"}, với tập tin đầy đủ sha256. Dấu vân tay và kích thước là những thông tin bạn đã gửi khi quá trình tải lên được tạo — chúng không được đọc lại từ yêu cầu này. Ba kết quả tương tự như trên: đã có trong tài khoản của bạn → 409 exists (không có gì được lưu trữ); sở hữu ở nơi khác → hoàn thành ngay lập tức (deduped); nếu không thì dấu vân tay chỉ va chạm và bạn sẽ nhận được kết quả bình thường upload_url / upload_token ticket - tải lên như ở bước 2 ở trên.

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

Trả về siêu dữ liệu cho một tệp bạn sở hữu.

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
}

Thăm dò nhẹ để biết trạng thái tải lên: pending, completed hoặc failed. Sau khi hoàn thành nó cũng trả về 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…"
}

Tạo URL tải xuống trực tiếp sẵn sàng sử dụng cho tệp bạn sở hữu. Liên kết truyền các byte ngay lập tức với không cần phiên trình duyệt (sử dụng nó từ tập lệnh/curl) và hết hạn sau ~5 phút. Yêu cầu đăng ký Premium đang hoạt động (quản trị viên luôn cho phép).

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
}

Thay đổi tên hiển thị của tệp bạn sở hữu. Liên kết chia sẻ (uuid) không thay đổi, do đó các liên kết bạn đã phân phát vẫn tiếp tục hoạt động — chỉ có tên hiển thị trên trang chia sẻ và được gửi cùng với các thay đổi tải xuống. Dấu phân cách đường dẫn và ký tự điều khiển bị loại bỏ; tên được giới hạn ở 512 ký tự.

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

Tệp một tệp bạn sở hữu vào một trong các thư mục của bạn. Gửi {"folder_id": 0} (hoặc bỏ qua nó) để di chuyển nó trở lại thư mục gốc. Thư mục phải là của bạn, nếu không 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
}

Đặt một tập tin ai đó khác được chia sẻ với bạn vào tài khoản của chính bạn, bằng liên kết chia sẻ của riêng bạn — tại đây {uuid} là nguồn sên chia sẻ tập tin, không phải của bạn. Không có byte nào được chuyển: bản sao sẽ trỏ đến cùng một đối tượng được lưu trữ nên nó sẽ hoàn thành ngay lập tức và được tính vào hạn mức bộ nhớ của bạn giống như bất kỳ tệp nào khác.

Nguồn phải công khai, hoàn chỉnh và chủ sở hữu của nó phải cho phép sao chép - nếu không bạn sẽ nhận được 403. 409 có nghĩa là nó đã là tệp của bạn (hoặc đã có trong tài khoản của bạn) và 403 cũng bao gồm "không còn đủ dung lượng lưu trữ". Các trường nội dung tùy chọn: folder_id, is_public (mặc định là đúng) và free_download (mặc định là sai).

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
}

Xóa mềm một tập tin bạn sở hữu; nó ngừng tải xuống ngay lập tức và byte của nó được lấy lại ngay sau đó.

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

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