Publish local files or public URLs through the API, MCP, the CLI, or the website.
On the website, the upload session auto-publishes one share link when the first file passes the safety check (one or more files, up to your tier's maximum). REST, MCP, and CLI upload calls each create a one-file share link. You can change sharing options after the link exists.
Add one or more files up to your tier's limit. When the first file passes the safety check, the session auto-publishes one canonical share link on the upload screen — you can keep editing settings or adding files afterward. Recipients can download files individually or together as a ZIP.
For a file under 4 MB, use POST /files/upload, beecargo_upload with contentBase64, or npx --yes github:Beecargo/cli upload ./file --json. Hosted MCP uses base64 because it cannot read local files.
Endpoint
Authentication
With an API key: send Authorization: Bearer YOUR_API_KEY.
Without a key: 1 GB per file; expires after 3 days.
Request examples
# For files < 4MB - Use Bearer token format (OAuth 2.0 standard)
curl -L -X POST https://api.beecargo.net/files/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/document.pdf"
# For files >= 4MB, use the client library examples below
# (multipart upload requires multiple API calls)
Anonymous Upload (NOT saved to account):
# File will NOT appear in your dashboard and expires in 3 days
curl -L -X POST https://api.beecargo.net/files/upload \
-F "file=@/path/to/document.pdf"Parameters
Usage notes
https://beecargo.net/d/{shortId}. Machine downloads still wait for the safety check.isAnonymous to true and expire after about 3 days. For safe retries on write requests, send an Idempotency-Key header.Tool
Authentication
API key optional. Anonymous uploads use anonymous limits and return claimToken and deletionToken.
Parameters
Usage notes
url (public HTTPS), contentBase64 (under 4MB on hosted MCP), or path (stdio only; auto multipart up to your tier max). Use background: true for large/slow URLs, then beecargo_upload_status.url or small contentBase64, or stdio/CLI for local files.ttl, once, protect, runId, openShare, …) can be set on upload; you can also change many of them later with share settings.runId, then list them at /docs/mcp/run-artifacts. For one human share link with many files, use openShare then shareShortId.idempotencyKey (same as the HTTP Idempotency-Key header)./files/multipart/* and /files/remote-upload for advanced integrators.Command
Authentication
Optional --key or BEECARGO_API_KEY. Anonymous uploads work without a key; save deletionToken and claimToken.
Usage notes
--json for a machine-readable share receipt.Use multipart upload through the API for local files over 4MB. A stdio MCP client can call beecargo_upload with path, which chooses multipart automatically and reports progress. The CLI upload command chooses multipart the same way.
Endpoint
Usage notes
ThreadPoolExecutor in Python).batch-urls before PUTs.Tool
Parameters
Usage notes
path; use url or small contentBase64 on the main upload page.Tool
Parameters
Usage notes
fileId, shortId, and sharePath.Command
Authentication
Optional --key or BEECARGO_API_KEY. Anonymous uploads work without a key; save deletionToken and claimToken.
Usage notes
--json for a machine-readable share receipt.If the file already has a public HTTPS URL, use remote upload or npx --yes github:Beecargo/cli remote <url> --json. Start an asynchronous job when you need progress for a long import.
Endpoint
Authentication
With an API key: send Authorization: Bearer YOUR_API_KEY.
Without a key: 1 GB per file; expires after 3 days; about 10 requests per hour per IP.
Request examples
# 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"
}'Parameters
Usage notes
POST /files/remote-multipart/init, then poll GET /files/remote-multipart/{jobId} or stream GET /files/remote-multipart/{jobId}/events (SSE). Status includes bytesDone, bytesTotal, and percent while importing. When status is completed, the response includes sharePath.https://beecargo.net/d/{shortId}. Machine downloads still wait for the safety check.isAnonymous to true, expire after about 3 days, and include a deletionToken. For safe retries, send an Idempotency-Key header.Tool
Authentication
API key optional. Best path for agent uploads with no human in the loop.
Parameters
Usage notes
url to beecargo_upload. Beecargo fetches the URL and stores the file. For large or slow sources, set background: true and poll with beecargo_upload_status.deletionToken and claimToken from anonymous responses.https://beecargo.net/d/{shortId}.protect, ttl, once, and runId.contentBase64 and stdio path.Command
Authentication
Optional --key or BEECARGO_API_KEY.
Usage notes
--async for a background job with progress on long imports.--json for a machine-readable share receipt.Direct and remote API uploads accept visibility, direct, retention, expiresAt, protect, and handoffMessage. Authenticated owners can change the same settings after upload.