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
PreviousShare & protectNextAgents
BlogPricingDashboardPrivacyTerms

Download and unlock

Open a share link, unlock a protected share, or request a signed download URL.

Start with the share address. Protection adds a second credential but does not change the public /d/{shortId} address.

Open a share

Open https://beecargo.net/d/{shortId}. That full share URL is the handoff. Recipients should not need a separate code-entry step.

Protected recipient flow

If the share asks for a code, enter the separate 6-character unlock code supplied by the sender. If the sender supplied a /h/{token} delivery link, open it instead; the token authorizes the share without typing the code.

  • Sharing and protection

API and agent flow

Machine downloads wait for the safety check to finish before a signed URL is issued.

Check unlockRequired in file or share metadata. POST /downloads/unlock accepts { shortId|fileId, unlockCode } or { handoffToken } and returns a short-lived unlockToken. Pass that token to the download endpoint, or pass the unlock code or handoff token directly.

APIRetrieve a fileGet a short-lived download URL for a file.+

Endpoint

GEThttps://api.beecargo.net/files/download/[fileId]

Authentication

No API key needed. If the share is protected, pass unlockCode, unlockToken, or handoffToken. Priced shares need purchaseToken (or owner auth).

Request examples

# Get download URL (unprotected)

curl https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000

# Protected share: unlock first, then download

curl -X POST https://api.beecargo.net/downloads/unlock \
  -H "Content-Type: application/json" \
  -d '{"shortId":"AbC123","unlockCode":"XyZ789"}'

curl "https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000?unlockCode=XyZ789"

# Download file directly

curl -L https://api.beecargo.net/files/download/550e8400-e29b-41d4-a716-446655440000 \
  -o downloaded-file.pdf

Parameters

ParameterTypeRequiredDescription
fileIdStringYesFile id from the upload response (short id, not a UUID)
unlockCodeStringNo6-character unlock code when the share is protected (query string)
unlockTokenStringNoShort-lived token from POST /downloads/unlock (query string)
handoffTokenStringNoPrivate token from /h/{token} (query string)
purchaseTokenStringNoRequired for priced shares after pay + POST /purchases/claim (query string)

Usage notes

  • Send the file id. You get a signed URL that expires in about 1 hour. For protected or priced shares, add credentials as query params.
  • Returns a signed download URL that expires in about 1 hour (3600 seconds).
  • After upload, Beecargo runs a safety check. The share link works right away. Downloads wait until that check finishes.
  • If a download is not ready yet, the response may include scanPending: true and retryAfterSeconds (about 15). Wait that long and try again, or wait for the file.ready webhook. Some clients also see errorCode: SCAN_PENDING.
  • If the file is unavailable after the check, download fails as not found / blocked (scanBlocked). Poll GET /files/share/{shortId} for scanStatus: pending, scanning, clean, or unavailable. Download only when it is clean.
  • File info does not include scanStatus. Use the share metadata route above for readiness.
  • The signed URL expires in about 1 hour
  • Each call to this endpoint counts as a download
  • Fetch the file from the signed URL, not from this endpoint
  • Check unlockRequired and paymentRequired / priceCents on GET /files/share/{shortId} or GET /files/info before downloading
  • Priced shares return HTTP 402 without purchaseToken (owners with auth may skip payment). CLI: beecargo download FILE_ID ./out --purchase-token TOKEN.
  • POST /downloads/unlock with { shortId|fileId, unlockCode } or { handoffToken } returns unlockToken for later download calls
  • Delivery links at /h/{token} unlock without typing the code; GET /files/handoff/{token} returns the message and shortId
Open: Retrieve a file
MCPRetrieve a fileGet a signed download URL by `fileId` via MCP.+

Tool

beecargo_get_download_url

Authentication

No API key required.

Parameters

ParameterTypeRequiredDescription
fileIdStringYesFile id from upload (data.id), not a UUID
unlockCodeStringNo6-character unlock code (needed when unlockRequired is true, unless you pass unlockToken or handoffToken)
unlockTokenStringNoShort-lived token from POST /downloads/unlock after a successful unlock
handoffTokenStringNoSecret from the delivery link /h/{token} (alternative to unlockCode)
purchaseTokenStringNoRequired for priced shares after the human pays on /d/{shortId} (from POST /purchases/claim)

Usage notes

  • Returns a temporary signed download URL for the given fileId. When the share is protected, pass unlockCode, unlockToken, or handoffToken. Priced shares also need purchaseToken (or owner auth).
  • After upload, Beecargo runs a safety check. Hand humans the share link right away. Wait for the check before machine downloads.
  • If this tool says the file is not ready, the body may include scanPending: true and retryAfterSeconds (about 15). Wait and retry, or wait for the file.ready webhook. Some responses use errorCode: SCAN_PENDING.
  • If the file is unavailable after the check, download fails as not found / blocked (scanBlocked). Poll GET /files/share/{shortId} for scanStatus (pending, scanning, clean, unavailable). Download only when it is clean.
  • beecargo_file_info does not include scanStatus. Use share metadata for readiness.
  • Signed URLs expire (usually about 1 hour). Request a fresh one when needed.
  • Check unlockRequired and paymentRequired / priceCents with beecargo_file_info or GET /files/share/{shortId} before calling this tool.
  • If unlockRequired is true, the /d/{shortId} link alone is not enough to download.
  • If payment is required (HTTP 402), call beecargo_purchase_checkout → send checkoutUrl → beecargo_purchase_claim → retry with purchaseToken. Or send the human to /d/{shortId}. CLI: beecargo download FILE_ID ./out --purchase-token TOKEN.
Open: Retrieve a file
CLICLI downloadDownload a file to a local path via a signed grant URL.+

Command

npx --yes github:Beecargo/cli download FILE_ID ./out.bin --key YOUR_BC_KEY

Authentication

Requires --key for owned files, or unlock / purchase credentials for protected or priced shares.

Usage notes

  • Optional --unlock-code, --unlock-token, or --handoff-token for protected shares.
  • Priced shares: pass --purchase-token from the paid claim flow (or download as the owner with --key).
  • Optional --sha256 verifies the digest after download.
CLICLI watch downloadsStream download events until a completed delivery.+

Command

npx --yes github:Beecargo/cli watch downloads FILE_ID --key YOUR_BC_KEY

Authentication

Requires --key or BEECARGO_API_KEY.

Usage notes

  • Useful for waiting on a human download of a share you published.
APIGet file infoLook up file details by short codes.+

Endpoint

GEThttps://api.beecargo.net/files/info

Authentication

Optional. You can send an API key in the Authorization header.

Request examples

# Get info for a single file

curl "https://api.beecargo.net/files/info?file_code=abc123"

# Get info for multiple files (comma-separated)

curl "https://api.beecargo.net/files/info?file_code=abc123,xyz789,def456"

# With API key authentication

curl "https://api.beecargo.net/files/info?file_code=abc123&key=YOUR_API_KEY"

# Or with Authorization header

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.beecargo.net/files/info?file_code=abc123,xyz789"

Parameters

ParameterTypeRequiredDescription
file_codeStringYesComma-separated short codes (e.g. "abc123,xyz789")

Response fields

FieldTypeDescription
msgStringResponse message ("OK" on success)
server_timeStringServer time as "YYYY-MM-DD HH:MM:SS"
statusNumberHTTP status (200 on success)
resultArrayList of file info objects
result[].statusNumber200 if found, 404 if not
result[].filecodeStringShort code (short_id) of the file
result[].nameStringFile name (when status is 200)
result[].sizeStringSize in bytes as a string (when status is 200)
result[].uploadedStringUpload time as "YYYY-MM-DD HH:MM:SS" (when status is 200)
result[].downloadStringDownload count as a string (when status is 200)
result[].status_fieldStringFile state: "active", "deleted", "dmca_removed", or "expired" (when status is 200)
result[].unlockRequiredBooleanTrue when download needs an unlock code or delivery link first (when status is 200)

Usage notes

  • Pass one or more short codes, separated by commas.
  • Returns an array of file objects. Each has a status of 200 (found) or 404 (not found).
  • You can look up several files at once with comma-separated short codes
  • Each item in result has its own status (200 or 404)
  • Only files with status "active" can be downloaded
  • This response does not include scanStatus. Poll GET /files/share/{shortId} before machine download.
  • When unlockRequired is true, GET /files/download/{fileId} needs unlockCode or unlockToken (or call POST /downloads/unlock with handoffToken from /h/{token})
  • Auth is optional; a key can help with rate limits
Open: Get file info
MCPGet file infoLook up file metadata by short codes via MCP.+

Tool

beecargo_file_info

Authentication

API key optional.

Parameters

ParameterTypeRequiredDescription
fileCodesStringYesComma-separated short codes, e.g. abc12,xyz99

Usage notes

  • Batch lookup with comma-separated short codes (the public share id).
  • Same idea as GET /files/info?file_code=… on the API.
  • This tool does not return scanStatus. Poll GET /files/share/{shortId} before machine download.
  • When a result has unlockRequired: true, call beecargo_get_download_url with unlockCode, unlockToken, or handoffToken. The share link alone is not enough to download.
Open: Get file info
CLICLI infoFetch file metadata by share short code.+

Command

npx --yes github:Beecargo/cli info SHORT_ID

Authentication

Optional --key when the file is owned.

Usage notes

  • Pass one or more short codes (comma-separated).