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
PreviousUpload & importNextShare & protect
BlogPricingDashboardPrivacyTerms

Own and organize files

Claim anonymous uploads, list files, organize folders, and delete files safely.

Anonymous uploads work without an account but return one-time ownership credentials. Save them if the file may need to be claimed or deleted later.

Claim an anonymous upload

Save fileId and claimToken from the upload response. After beecargo register --save or supplying an API key, claim with npx --yes github:Beecargo/cli claim FILE_ID CLAIM_TOKEN, or use the API / MCP.

APIClaim a fileMove an anonymous upload into your account with the file id and claim token from the upload response.+

Endpoint

POSThttps://api.beecargo.net/files/claim

Authentication

Required. Use an API key from agent register (MCP/CLI or challenge + PoW + POST /agent/register), or a dashboard API key with write access.

Request examples

curl -X POST https://api.beecargo.net/files/claim \
  -H "Authorization: Bearer YOUR_BC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId":"abc12xyz","claimToken":"YOUR_CLAIM_TOKEN"}'

Parameters

ParameterTypeRequiredDescription
fileIdStringYesShort file id from upload (data.id), not a UUID
claimTokenStringYesclaimToken from the anonymous upload response

Usage notes

  • Moves an anonymous file into your account so it shows in GET /files/list and uses signed-in retention limits.
  • MCP: call beecargo_claim_file after beecargo_register_agent
  • Claim only works for anonymous uploads that returned a claimToken
Open: Claim a file
MCPClaim fileMove an anonymous upload into your agent account using the claim token from the upload response.+

Tool

beecargo_claim_file

Authentication

Needs an API key (from beecargo_register_agent or x-beecargo-api-key).

Parameters

ParameterTypeRequiredDescription
fileIdStringYesShort file id from upload (data.id), not a UUID
claimTokenStringYesclaimToken from the anonymous upload response

Usage notes

  • Anonymous uploads return a claim token with the file id. Claim attaches the file to your account so it shows in your file list and uses signed-in retention limits.
  • API equivalent: POST https://api.beecargo.net/files/claim with Authorization: Bearer …
  • If you registered in this session, you do not need to paste the key again for MCP.
Open: Claim file
CLICLI claimAttach an anonymous upload to your API key.+

Command

npx --yes github:Beecargo/cli claim FILE_ID CLAIM_TOKEN --key YOUR_BC_KEY

Authentication

Requires --key or a saved key from register --save.

Usage notes

  • Use fileId and claimToken from the upload response.
  • Do not confuse claimToken with deletionToken.

Files and folders

Authenticated identities can list files, create folders, and filter by folder. From a terminal: npx --yes github:Beecargo/cli list --key YOUR_BC_KEY, folders list, and folders create NAME.

APIList files and foldersList your files. When you list a folder, you can also get its subfolders.+

Endpoint

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

Authentication

Required. Send Authorization: Bearer YOUR_API_KEY.

Request examples

# List all files (first page, 50 per page)

curl https://api.beecargo.net/files/list \
  -H "Authorization: Bearer YOUR_API_KEY"

# With pagination

curl "https://api.beecargo.net/files/list?page=2&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by folder

curl "https://api.beecargo.net/files/list?folderId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List files in root folder only (no folder)

curl "https://api.beecargo.net/files/list?folderId=null" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List folder contents (files + subfolders)

curl "https://api.beecargo.net/files/list?folderId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

ParameterTypeRequiredDescription
pageInteger1Page number (ignored when runId is set)
limitInteger50Files per page (max 200). With runId, max 500 (default 100)
folderIdString-Filter by folder. Use "null" for root only. Ignored when runId is set.
includeFoldersBooleantrueWhen true, the response includes a folders array for that folder (or root). Set to "false" for files only. Ignored when runId is set.
runIdString-When set, list files uploaded with this pipeline id (GET /files/run/{runId} is an alias)

Usage notes

  • List your uploaded files with pagination.
  • data holds files. folders is included when you list a folder and includeFolders is true. With runId, the response is a run artifact list (data.runId + data.artifacts) instead of the paginated library shape.
  • To list folders only (all folders or children of a parent), use the folders endpoint. Same API key as above.
  • Query params: parentId (folder UUID or "null" for root), page, limit, search. Response: { success, data: [ folders ], pagination }. Each folder includes id, name, parent_id, file_count, and total_size when not searching.
Open: List files and folders
MCPList filesList files owned by the API key attached to the MCP session.+

Tool

beecargo_list_files

Authentication

API key required (BEECARGO_API_KEY, x-beecargo-api-key, or register an agent first).

Parameters

ParameterTypeRequiredDescription
pageNumberNoPage number (default 1); ignored when runId is set
limitNumberNoPage size (default 50). Max 200 for library list; max 500 when runId is set
folderIdStringNoOptional folder UUID filter; ignored when runId is set
includeFoldersBooleanNoInclude sibling folders in the response (default true); ignored when runId is set
runIdStringNoWhen set, list files uploaded with this run id (GET /files/list?runId=)

Usage notes

  • Lists files for the account or agent key on this MCP session. Pass runId to list only files uploaded with that pipeline id (same as the former dedicated run-artifacts tool).
  • Anonymous sessions cannot list. Register an agent or set a key first.
  • Reuse the same runId on beecargo_upload across outputs, then list with runId here.
Open: List files
MCPbeecargo_foldersCreate a folder or list folder trees for the API key.+

Tool

beecargo_folders

Parameters

ParameterTypeRequiredDescription
actioncreate | listYescreate makes a folder; list returns folders
nameStringcreateFolder name, maximum 200 characters
parentIdUUID | nullNocreate: parent folder or null for root; list: only children of this folder
pageIntegerNolist only: page number, default 1
limitIntegerNolist only: page size, maximum 200
searchStringNolist only: folder name search

Usage notes

  • Use the returned folder id as folderId or parentId.
  • Use beecargo_list_files with includeFolders: true for a combined view.
Open: beecargo_folders
CLICLI listList files owned by your API key.+

Command

npx --yes github:Beecargo/cli list --key YOUR_BC_KEY

Authentication

Requires --key or BEECARGO_API_KEY.

Usage notes

  • Use --page and --limit to page through larger libraries.
  • Add --include-folders or --folder-id when organizing a library.
CLICLI foldersList or create folders for your API key.+

Command

npx --yes github:Beecargo/cli folders list --key YOUR_BC_KEY

Authentication

Requires --key or BEECARGO_API_KEY.

Usage notes

  • folders list and folders create NAME match the folder API / MCP tools.

Delete

Owned files use an API key. Anonymous files use the deletionToken returned once by upload. Do not confuse it with the claimToken. From a terminal, use npx --yes github:Beecargo/cli delete FILE_ID --key YOUR_BC_KEY or --token DELETION_TOKEN.

APIDelete a filePermanently delete a file from your account.+

Endpoint

DELETEhttps://api.beecargo.net/files/delete?fileId=FILE_ID

Authentication

Required. Send Authorization: Bearer YOUR_API_KEY. You can only delete files you own.

Anonymous files: delete with the token from upload: ?fileId=FILE_ID&token=DELETION_TOKEN

Request examples

# Delete a file with API key

curl -X DELETE "https://api.beecargo.net/files/delete?fileId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete an anonymous file with deletion token (no API key needed)

curl -X DELETE "https://api.beecargo.net/files/delete?fileId=550e8400-e29b-41d4-a716-446655440000&token=YOUR_DELETION_TOKEN"

Parameters

ParameterTypeRequiredDescription
fileIdStringYesFile id from upload (data.id), not a UUID
tokenStringNo*Deletion token for anonymous files (instead of an API key)

Usage notes

  • Delete a file by id. This cannot be undone.
  • * The token param is only needed when deleting anonymous files without an API key.
  • Deletion is permanent
  • You can only delete files you own
  • The file is removed from storage and the database
  • Download stats for that file are removed too
Open: Delete a file
MCPDelete a fileDelete a file by `fileId` via MCP.+

Tool

beecargo_delete_file

Authentication

API key for owned files, or deletionToken for anonymous uploads.

Parameters

ParameterTypeRequiredDescription
fileIdStringYesFile id from the upload response
deletionTokenStringNoRequired for anonymous deletes when no API key owns the file

Usage notes

  • Deletes the file from storage. Anonymous uploads must pass the deletionToken returned at upload time.
  • This cannot be undone.
Open: Delete a file
CLICLI deleteDelete a file with an owner key or anonymous deletion token.+

Command

npx --yes github:Beecargo/cli delete FILE_ID --key YOUR_BC_KEY

Authentication

Owned files: --key. Anonymous files: --token DELETION_TOKEN.

Usage notes

  • Do not confuse deletionToken with claimToken.
  • Add --force only when the API requires it for dependent files.