Beecargo

Get set up

  • ○Sign in
  • ○Connect your agent
  • ○Share a file

INTRODUCTION

WelcomeSecurity

Guides

Overview
Upload & import
Own & organize
Share & protect
Download & unlock
Agents

SUPPORT

Contact

LEGAL

PrivacyTermsAcceptable useCookiesRefundsDMCA
PreviousOwn & organizeNextDownload & unlock
BlogPricingDashboardPrivacyTerms

Share and protect

Control who can discover a share, how long it lasts, and whether download requires a secret.

A share address and an unlock secret solve different problems. The share code locates a file; an unlock code or private delivery link authorizes a protected download.

Share code

The shortId in /d/{shortId} identifies the share. Always hand off the full URL https://beecargo.net/d/{shortId}. It is an address, not a password.

  • Recipient guide

Visibility, retention, and direct download

unlisted is reachable only by its link. public may appear on /u/{username} and requires a claimed username. Public Free shares use a 7-day TTL; Pro can use a TTL or forever. While Pro is active, your uploads sponsor ad-free, wait-free downloads for every recipient. Pro direct: true only auto-starts the download when /d/{shortId} opens.

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

ParameterTypeRequiredDescription
fileIdStringYesFile id from the upload response
visibilityunlisted | publicNoPublic visibility requires a claimed username
priceCentsInteger | nullNoOne-time USD price in cents (minimum 100). Pass 0 or null to clear. Positive prices require seller Connect ready to sell.
directBooleanNoPro: start download when the /d share opens
retentionttl | foreverNoPublic Pro shares may use forever
expiresAtString (ISO)NoFuture expiration when retention is ttl; maximum 90 days from now
extendTtlStringNoAdd more keep time from now (for example 7d). Useful after an upgrade when you want a longer Free or Pro TTL without picking an exact date.
protectBooleanNoTrue creates new unlock credentials; false clears existing protection
handoffMessageString | nullNoOptional delivery-link note, maximum 480 characters
immutableBooleanNoWhen true, the file cannot be casually changed or deleted. Use for outputs that other files depend on.
upstreamFileIdsString[]NoParent file ids this share came from. Helps keep a simple lineage for pipeline outputs.

Usage notes

  • Use this endpoint after upload. The same options can also be sent during direct or remote upload.
  • When protection is enabled, unlockCode and handoffUrl are returned once. Save them before discarding the response.
  • 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.
  • A positive priceCents requires connected seller payouts (POST /connect with action=onboard). Buyers pay on /d/{shortId} before download unlocks.
  • Free public shares last 7 days. Pro defaults to forever while subscribed and can choose any expiry date within 90 days.
  • CLI beecargo share updates the same fields (--visibility, --price-cents, --protect, …). beecargo extend FILE_ID 7d is a shortcut for --extend-ttl.
  • Setting protect: true again rotates the unlock credentials.
Open: Share settings
MCPUpdate share settingsChange visibility, one-time price, direct download, public retention, and optional unlock protection on a file or growable Shipment you own.+

Tool

beecargo_update_share_settings

Authentication

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

Parameters

ParameterTypeRequiredDescription
fileIdStringNoFile id from the upload response (required if shortId is omitted)
shortIdStringNoShare shortId — one-file share or growable Shipment from openShare (required if fileId is omitted)
visibilityunlisted | publicNoPublic needs a claimed username on the account
priceCentsInteger | nullNoOne-time price in the smallest currency unit (minimum 100). Pass 0 or null to clear. Positive prices require seller Connect readyToSell. Pair with currency (default usd).
currencyusd | eur | aed | brl | jpy | krw | cny | rubNoCharge currency for priceCents. Defaults to usd. JPY and KRW use whole units (no cents).
directBooleanNoPro only: auto-start download when the /d link opens
retentionttl | foreverNoPublic + Pro only for forever
expiresAtString (ISO)NoExpiry when retention is ttl
extendTtlStringNoAdd more keep time from now (for example 7d) without picking an exact expiry date
protectBooleanNoWhen true, create a download unlock code and delivery link (returned once). When false, clear protection.
handoffMessageStringNoOptional note (max 480 chars) shown on the delivery link /h/{token}
immutableBooleanNoWhen true, the file cannot be casually changed or deleted
upstreamFileIdsString[]NoOptional parent file ids for pipeline lineage

Usage notes

  • Use after upload, or when someone upgrades to Pro and wants forever retention or a new TTL. Set priceCents for a paid share (seller Connect must be ready). Set protect to create unlock credentials. For growable Shipments from openShare, pass shortId (or the member fileId). Maps to PATCH /files/share-settings.
  • Pass at least one of fileId or shortId.
  • Before a positive priceCents, call beecargo_connect with action=onboard / action=status until readyToSell.
  • Buyers pay on the human share page /d/{shortId} — not through this tool.
  • Free public shares last 7 days; forever and direct need Pro.
  • While Pro is active, recipients get sponsored ad-free, wait-free downloads on your links without signing in.
  • Upgrading to Pro does not rewrite existing Free public TTLs. Call this tool with extendTtl or set forever.
  • CLI beecargo share covers the same fields (--price-cents, --protect, …). beecargo extend is the same idea as extendTtl here.
  • 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}.
  • For a growable multi-file Shipment, protect on shortId unlocks the whole set — not each member file separately.
Open: Update share settings
CLICLI shareUpdate share settings on an owned file or Shipment.+

Command

npx --yes github:Beecargo/cli share FILE_ID --visibility public --key YOUR_BC_KEY

Authentication

Requires --key or BEECARGO_API_KEY.

Usage notes

  • Pass fileId and/or --short-id. Use --price-cents (min 100) after Connect is ready to sell; 0 clears the price.
  • extend FILE_ID 7d is a shortcut for share --extend-ttl.

Unlock code and delivery link

Set protect: true to create a 6-character unlock code and a private delivery link. Both are returned once. An optional message of up to 480 characters is shown on the delivery page.

Send the public /d address and unlock code through separate channels, or send only the private /h/{token} delivery link. The delivery link skips typing the unlock code.

  • API share settings
  • Download and unlock

Anonymous protection

Anonymous direct uploads can request protection during upload. After upload, PATCH /files/link-protection can enable or clear protection with fileId and claimToken without first claiming the file.

APIProtect an anonymous uploadUse `PATCH /files/link-protection` before claiming a file. Send the `fileId` and `claimToken` returned by upload, plus `protect` and an optional `handoffMessage`.+

Endpoint

PATCHhttps://api.beecargo.net/files/link-protection

Parameters

ParameterTypeRequiredDescription
fileIdStringYesAnonymous file id
claimTokenStringYesClaim token returned once by upload
protectBooleanYesEnable or clear protection
handoffMessageString | nullNoOptional delivery-link note
Open: Protect an anonymous upload