Remote upload

POST https://api.beecargo.net/files/remote-upload

Use this endpoint for remote uploads. The API streams the remote body to R2 (no full-file RAM buffer). For fire-and-forget large imports, use the async remote-multipart job endpoints.

Option 1: API key with Bearer token (recommended) - Include your API key in the Authorization header using the Bearer token format (OAuth 2.0 standard). Create an API key in your dashboard settings. Agent bootstrap keys are free-tier; Premium-minted agent keys get higher remote/hour quotas.

Authorization: Bearer YOUR_API_KEY

Option 2: Anonymous upload - No authentication required. Limited to 25GB per file, expires after 7 days. Rate limited to 10 uploads per hour per IP address.

Anonymous users: Limited to 10 remote uploads per hour per IP address.

Authenticated humans: no separate remote hourly cap (global API rate still applies). Agent keys: 30/hour bootstrap, 300/hour Premium-minted.

Upload a file from any publicly accessible URL. The API downloads from the remote server and streams it into Beecargo storage.

Large files: remote-upload streams via multipart put to R2. Prefer POST /files/remote-multipart/init when you want an async job (poll GET /files/remote-multipart/{jobId}; response includes sharePath when completed).

# Upload from remote URL

curl -X POST https://api.beecargo.net/files/remote-upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/video.mp4",
    "folderId": null
  }'

Anonymous Upload (NOT saved to account):

# File will NOT appear in your dashboard and expires in 7 days

curl -X POST https://api.beecargo.net/files/remote-upload \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/document.pdf"
  }'

The URL returned is a temporary signed URL valid for 24 hours. For permanent access, use the short URL: https://beecargo.net/d/${shortId}

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "video.mp4",
    "size": 52428800,
    "url": "https://signed-url.cloudflare.com/...",
    "mimeType": "video/mp4",
    "createdAt": "2025-12-06T12:00:00.000Z",
    "isAnonymous": false,
    "expiresAt": null,
    "shortId": "abc123"
  }
}

Note: Anonymous uploads will have isAnonymous: true, expiresAt set to 7 days from upload, and include a deletionToken for managing the file.

Common error responses:

// Invalid or missing URL
{
  "success": false,
  "error": "No URL provided. Please provide a valid URL in the request body."
}

// Rate limit exceeded (anonymous users)
{
  "success": false,
  "error": "Rate limit exceeded. Anonymous users can upload 10 files from remote URLs per hour. Try again in 45 minutes.",
  "rateLimitExceeded": true,
  "resetAt": "2025-12-06T13:45:00.000Z"
}

// Remote server error
{
  "success": false,
  "error": "Failed to download file from URL",
  "remoteStatus": 403
}

// File too large for anonymous users
{
  "success": false,
  "error": "Anonymous uploads are limited to 25GB. Please create an account for larger files."
}

• Direct download links (HTTP/HTTPS only)
• URLs with proper Content-Length headers (recommended for quota checks)
• URLs that don't require authentication or browser interaction
• CDN links and object storage URLs (S3, R2, etc.)

• File hosting services that require browser interaction are not supported (e.g., MediaFire, Mega.nz with captchas)
• URLs requiring authentication or login cannot be used
• Anonymous uploads: 10 per hour per IP, max 25GB per file, expires after 7 days
• Download timeout: 5 minutes maximum for the initial request / stream window
• Content-Length is recommended; without it size is enforced while streaming

Best practice: use /files/remote-upload for most agent imports. Use remote-multipart when you need async status polling. Always share https://beecargo.net/d/{shortId} with humans.