Upload and import

Publish local files or public URLs through the API, MCP, the CLI, or the website.

Choose a method based on where the file is and its size. You can set sharing options now or change them later.

Small local files

For a file under 4 MB, use POST /files/upload or beecargo_upload_file. Hosted MCP uses base64 because it cannot read local files.

APIUpload a fileSend a file to Beecargo with the HTTP API.

Endpoint

POSThttps://api.beecargo.net/files/upload

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

Parameter	Type	Required	Description
`file`	File	Yes	The file to upload
`folderId`	String	No	Optional folder id
`visibility`	unlisted \| public	No	Public requires a claimed username
`direct`	Boolean	No	Premium: start download when the share opens
`retention`	ttl \| forever	No	Public Premium shares may use `forever`
`expiresAt`	String (ISO)	No	Explicit expiration for TTL retention
`protect`	Boolean	No	Create a one-time unlock code and private delivery link
`handoffMessage`	String	No	Optional delivery-link note, maximum 480 characters

Usage notes

Use this for files under 4MB. The samples below also show how larger files use multipart upload.
The response includes a temporary signed URL (about 24 hours). For a lasting share link, use https://beecargo.net/d/{shortId}.
Anonymous uploads set isAnonymous to true and expire after about 3 days.

Open: Upload a file

MCPUpload a fileUpload a small file via MCP (base64, under 4MB).

Tool

beecargo_upload_file

Authentication

API key optional. Anonymous uploads use free limits and return claimToken and deletionToken.

Parameters

Parameter	Type	Required	Description
`fileName`	String	Yes	Original file name
`contentBase64`	String	Yes	File contents as base64
`contentType`	String	No	MIME type (default `application/octet-stream`)
`folderId`	String	No	Optional folder UUID (signed-in users only)

Usage notes

For files under 4MB. For larger files, prefer beecargo_remote_upload or API multipart upload.
Payloads over 4MB are rejected on this tool. Prefer beecargo_upload_path (stdio, auto multipart + progress), beecargo_remote_upload, or API multipart.
See [Large uploads and jobs](/docs/mcp/large-uploads) for beecargo_upload_path, multipart, and asynchronous remote-import tools.
Anonymous responses include share URL, fileId, claimToken, and deletionToken. Anonymous max file size is 1GB.

Open: Upload a file

Large local files

Use multipart upload through the API for local files over 4MB. A stdio MCP client can use beecargo_upload_path, which chooses multipart automatically and reports progress.

API3–6× faster uploadsThe samples pick the right path for you. Files under 4MB use a direct upload. Larger files use multipart. Call `uploadFile()` and let the sample handle the rest.

Endpoint

POST/files/multipart/init → PUT parts → POST /files/multipart/complete

Usage notes

Samples upload parts one after another. That is slower than parallel uploads, but more reliable on proxies, VPNs, and flaky networks.
Basic samples upload chunks one by one. Parallel samples upload several chunks at once, closer to the Beecargo website speed.
Several chunks upload at the same time (ThreadPoolExecutor in Python, Promise.all in JavaScript).
Worker count scales with file size (about 3–6).
Presigned URLs are fetched up front so chunks do not wait on each other.
Each chunk can retry on its own.
Progress counts finished chunks across all workers.

Open: 3–6× faster uploads

MCPbeecargo_upload_pathStdio only: read a local path, choose direct or multipart automatically, and emit progress.

Tool

beecargo_upload_path

Parameters

Parameter	Type	Required	Description
`path`	String	Yes	Absolute or relative local filesystem path
`contentType`	String	No	MIME type; defaults to `application/octet-stream`
`folderId`	String	No	Destination folder for an authenticated identity

Usage notes

Unavailable on hosted HTTP MCP because the server cannot read client files.

Open: beecargo_upload_path

MCPbeecargo_multipart_initStart a client multipart upload and receive the upload session.

Tool

beecargo_multipart_init

Parameters

Parameter	Type	Required	Description
`fileName`	String	Yes	Original filename
`fileSize`	Integer	Yes	Total bytes
`fileType`	String	No	MIME type
`folderId`	String	No	Destination folder

Usage notes

Save key, uploadId, chunkSize, and totalParts.

Open: beecargo_multipart_init

MCPbeecargo_multipart_batch_urlsGet presigned PUT URLs for all multipart parts.

Tool

beecargo_multipart_batch_urls

Parameters

Parameter	Type	Required	Description
`key`	String	Yes	Object key from multipart init
`uploadId`	String	Yes	Upload id from multipart init
`totalParts`	Integer	Yes	Part count from multipart init
`uploadSessionToken`	String	No	Session secret when returned by init

Usage notes

PUT raw bytes to every URL and preserve each response ETag.

Open: beecargo_multipart_batch_urls

MCPbeecargo_multipart_completeFinalize all uploaded parts and create the file record.

Tool

beecargo_multipart_complete

Parameters

Parameter	Type	Required	Description
`key / uploadId`	String	Yes	Multipart session identifiers
`parts`	Array	Yes	`[{ partNumber, etag }]` for every uploaded part
`fileName / fileSize`	String / Integer	Yes	Original file metadata
`contentType / folderId`	String	No	MIME type and destination folder

Usage notes

The completed response contains fileId, shortId, and share URL.

Open: beecargo_multipart_complete

MCPbeecargo_multipart_abortAbort an unfinished multipart upload.

Tool

beecargo_multipart_abort

Parameters

Parameter	Type	Required	Description
`key`	String	Yes	Object key from multipart init
`uploadId`	String	Yes	Upload id from multipart init

Usage notes

Use when the client cannot complete all parts.

Open: beecargo_multipart_abort

Files already on the web

If the file already has a public HTTPS URL, use remote upload. Start an asynchronous job when you need progress for a long import.

APIRemote uploadPull a file into Beecargo from a public URL.

Endpoint

POSThttps://api.beecargo.net/files/remote-upload

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

Parameter	Type	Required	Description
`url`	String	Yes	Public URL of the file to import
`folderId`	String	No	Optional folder id (signed-in users only)
`visibility`	unlisted \| public	No	Public requires a claimed username
`direct`	Boolean	No	Premium: start download when the share opens
`retention`	ttl \| forever	No	Public Premium shares may use `forever`
`expiresAt`	String (ISO)	No	Explicit expiration for TTL retention
`protect`	Boolean	No	Create a one-time unlock code and private delivery link
`handoffMessage`	String	No	Optional delivery-link note, maximum 480 characters

Usage notes

Beecargo fetches the URL and stores the file. For very large imports you can start an async job and poll until it finishes.
For long-running imports, use 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.
You get a temporary signed URL (about 24 hours). Share the lasting link: https://beecargo.net/d/{shortId}.
Anonymous imports set isAnonymous to true, expire after about 3 days, and include a deletionToken.

Open: Remote upload

MCPRemote uploadImport a file from a public HTTPS URL via MCP.

Tool

beecargo_remote_upload

Authentication

API key optional. Best path for agent uploads with no human in the loop.

Parameters

Parameter	Type	Required	Description
`url`	String	Yes	Public HTTPS URL to fetch
`folderId`	String	No	Optional folder UUID (signed-in users only)
`visibility`	unlisted \| public	No	Public needs a username; Free public TTL is 7 days
`direct`	Boolean	No	Premium: auto-download on the `/d` link
`retention`	ttl \| forever	No	Public + Premium for forever
`expiresAt`	String (ISO)	No	Expiry when retention is `ttl`

Usage notes

Beecargo fetches the URL and stores the file. Prefer this over base64 upload when the file is already on the public web.
Save deletionToken and claimToken from anonymous responses.
Share links look like https://beecargo.net/d/{shortId}.

Open: Remote upload

MCPbeecargo_remote_multipart_initStart a background import from a public URL.

Tool

beecargo_remote_multipart_init

Parameters

Parameter	Type	Required	Description
`url`	String (URL)	Yes	Public source URL
`folderId`	String	No	Destination folder

Usage notes

Save jobId and jobSecret from the response.

Open: beecargo_remote_multipart_init

MCPbeecargo_remote_multipart_statusPoll a remote job or wait while MCP progress notifications are emitted.

Tool

beecargo_remote_multipart_status

Parameters

Parameter	Type	Required	Description
`jobId`	UUID	Yes	Job id from remote multipart init
`jobSecret`	String	No	Secret returned for new jobs
`waitSeconds`	Integer	No	Poll for up to 600 seconds

Usage notes

Completed jobs include fileId, shortId, and sharePath.

Open: beecargo_remote_multipart_status

Direct and remote API uploads accept visibility, direct, retention, expiresAt, protect, and handoffMessage. Authenticated owners can change the same settings after upload.

APIShare settingsMake a file public, change retention, enable direct download, or require an unlock secret.

Endpoint

PATCHhttps://api.beecargo.net/files/share-settings

Authentication

API key required for PATCH /files/share-settings. The key must own the claimed file.

Request examples

curl -X PATCH https://api.beecargo.net/files/share-settings \
  -H "Authorization: Bearer YOUR_BC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId":"abc12xyz","visibility":"public","retention":"ttl","protect":true,"handoffMessage":"Private files for review"}'

Parameters

Parameter	Type	Required	Description
`fileId`	String	Yes	File id from the upload response
`visibility`	unlisted \| public	No	Public visibility requires a claimed username
`direct`	Boolean	No	Premium: start download when the `/d` share opens
`retention`	ttl \| forever	No	Public Premium shares may use `forever`
`expiresAt`	String (ISO)	No	Future expiration when retention is `ttl`; maximum 90 days from now
`protect`	Boolean	No	True creates new unlock credentials; false clears existing protection
`handoffMessage`	String \| null	No	Optional delivery-link note, maximum 480 characters

Usage notes

Use this endpoint after upload. The same options can also be sent during direct or remote upload.
shortId is the public share code. It locates /d/{shortId} and is not the unlock secret.
Send the public share address and unlockCode through separate channels, or send the private handoffUrl.
Free public shares last 7 days. Premium defaults to forever while subscribed and can choose any expiry date within 90 days.
Setting protect: true again rotates the unlock credentials.

Open: Share settings

MCPUpdate share settingsChange visibility, direct download, public retention, and optional unlock protection on a file you own.

Tool

beecargo_update_share_settings

Authentication

API key required. The file must be owned and claimed (not anonymous).

Parameters

Parameter	Type	Required	Description
`fileId`	String	Yes	File id from the upload response
`visibility`	unlisted \| public	No	Public needs a claimed username on the account
`direct`	Boolean	No	Premium only: auto-start download when the `/d` link opens
`retention`	ttl \| forever	No	Public + Premium only for forever
`expiresAt`	String (ISO)	No	Expiry when retention is `ttl`
`protect`	Boolean	No	When true, create a download unlock code and delivery link (returned once). When false, clear protection.
`handoffMessage`	String	No	Optional note (max 480 chars) shown on the delivery link `/h/{token}`

Usage notes

Use after upload, or when someone upgrades to Premium and wants forever retention or a new TTL. Set protect to create unlock credentials. Maps to PATCH /files/share-settings.
Free public shares last 7 days; forever and direct need Premium.
While Premium is active, recipients get sponsored ad-free, wait-free downloads on your links without signing in.
Upgrading to Premium does not rewrite existing Free public TTLs. Call this tool to extend or set forever.
When protect is on, the response includes unlockCode and handoffUrl once. Share both on a private channel. The /d link alone is not enough to download.
Recipients can open handoffUrl (message + unlock) or type unlockCode on /d/{shortId}.

Open: Update share settings

Share and protect

Small local files

Large local files

Files already on the web

Share options during upload

Small local files

Large local files

Files already on the web

Share options during upload