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.

The shortId in /d/{shortId} is the share code. A recipient can open the full URL or enter only that code at https://beecargo.net/get. 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; Premium can use a TTL or forever. While Premium is active, your uploads sponsor ad-free, wait-free downloads for every recipient. Premium 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

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.
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.
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

Unlock code and delivery link

Set protect: true to mint a 6-character unlockCode and private handoffUrl. Both are returned once. A handoffMessage 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.

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

Parameter	Type	Required	Description
`fileId`	String	Yes	Anonymous file id
`claimToken`	String	Yes	Claim token returned once by upload
`protect`	Boolean	Yes	Enable or clear protection
`handoffMessage`	String \| null	No	Optional delivery-link note

Open: Protect an anonymous upload

Visibility, retention, and direct download

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.
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.
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

Unlock code and delivery link

Set protect: true to mint a 6-character unlockCode and private handoffUrl. Both are returned once. A handoffMessage 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.

Anonymous protection

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

Parameter	Type	Required	Description
`fileId`	String	Yes	Anonymous file id
`claimToken`	String	Yes	Claim token returned once by upload
`protect`	Boolean	Yes	Enable or clear protection
`handoffMessage`	String \| null	No	Optional delivery-link note

Open: Protect an anonymous upload

Share code

Visibility, retention, and direct download

Unlock code and delivery link

Anonymous protection

Share code

Visibility, retention, and direct download

Unlock code and delivery link

Anonymous protection