Retrieve a file

No API key needed. If the share is protected, pass unlockCode, unlockToken, or handoffToken. Priced shares need purchaseToken (or owner auth).

Send the file id. You get a signed URL that expires in about 1 hour. For protected or priced shares, add credentials as query params.

# Get download URL (unprotected)

curl https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000

# Protected share: unlock first, then download

curl -X POST https://api.beecargo.net/downloads/unlock \
  -H "Content-Type: application/json" \
  -d '{"shortId":"AbC123","unlockCode":"XyZ789"}'

curl "https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000?unlockCode=XyZ789"

# Download file directly

curl -L https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000 \
  -o downloaded-file.pdf

Returns a signed download URL that expires in about 1 hour (3600 seconds).

{
  "success": true,
  "data": {
    "url": "https://signed-url.cloudflare.com/...",
    "fileName": "document.pdf",
    "size": 1048576,
    "mimeType": "application/pdf",
    "expiresIn": 3600,
    "expiresAt": null,
    "downloads": 42,
    "canDelete": false,
    "shortId": "abc123"
  }
}

• After upload, Beecargo runs a safety check. The share link works right away. Downloads wait until that check finishes.
• If a download is not ready yet, the response may include scanPending: true and retryAfterSeconds (about 15). Wait that long and try again, or wait for the file.ready webhook. Some clients also see errorCode: SCAN_PENDING.
• If the file is unavailable after the check, download fails as not found / blocked (scanBlocked). Poll GET /files/share/{shortId} for scanStatus: pending, scanning, clean, or unavailable. Download only when it is clean.
• File info does not include scanStatus. Use the share metadata route above for readiness.
• The signed URL expires in about 1 hour
• Each call to this endpoint counts as a download
• Fetch the file from the signed URL, not from this endpoint
• Check unlockRequired and paymentRequired / priceCents on GET /files/share/{shortId} or GET /files/info before downloading
• Priced shares return HTTP 402 without purchaseToken (owners with auth may skip payment). CLI: beecargo download FILE_ID ./out --purchase-token TOKEN.
• POST /downloads/unlock with { shortId|fileId, unlockCode } or { handoffToken } returns unlockToken for later download calls
• Delivery links at /h/{token} unlock without typing the code; GET /files/handoff/{token} returns the message and shortId