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
`priceCents`	Integer \| null	No	One-time USD price in cents (minimum 100). Pass 0 or null to clear. Positive prices require seller Connect ready to sell.
`direct`	Boolean	No	Pro: start download when the `/d` share opens
`retention`	ttl \| forever	No	Public Pro shares may use `forever`
`expiresAt`	String (ISO)	No	Future expiration when retention is `ttl`; maximum 90 days from now
`extendTtl`	String	No	Add 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.
`protect`	Boolean	No	True creates new unlock credentials; false clears existing protection
`handoffMessage`	String \| null	No	Optional delivery-link note, maximum 480 characters
`immutable`	Boolean	No	When true, the file cannot be casually changed or deleted. Use for outputs that other files depend on.
`upstreamFileIds`	String[]	No	Parent file ids this share came from. Helps keep a simple lineage for pipeline outputs.

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

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