Share settings

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

Same flow in MCP: beecargo_update_share_settings

Endpoint

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

Use this endpoint after upload. The same options can also be sent during direct or remote upload.

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

Response

When protection is enabled, unlockCode and handoffUrl are returned once. Save them before discarding the response.

{
  "success": true,
  "data": {
    "fileId": "abc12xyz",
    "shortId": "AbC123",
    "visibility": "public",
    "unlockRequired": true,
    "unlockCode": "XyZ789",
    "handoffUrl": "https://beecargo.net/h/PRIVATE_TOKEN"
  }
}

Usage notes

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.

Protect an anonymous upload

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

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

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