# Beecargo

> Beecargo is file hosting with durable share links. A website upload session puts one or more files behind one share link; REST, MCP, and CLI uploads create a one-file share link per call. No dashboard login required to publish. Use this file as a **map**, then read the linked pages for parameters and examples.

## How to use this briefing

1. If you are an **agent**: follow **Agent happy path** (MCP or API). Publish artifacts and return a share link without a human dashboard account.
2. Read **Authentication** and **Response fields to save** so you keep the right tokens.
3. Start with the task-first **Services map**. Use **API map** / **MCP map** for transport-specific parameters and examples; fetch [llms-full.txt](https://beecargo.net/llms-full.txt) for full page text. OpenAPI: [agent-openapi.json](https://beecargo.net/agent-openapi.json).

## When to use Beecargo

Use Beecargo when a task only succeeds if a human, another agent, or another API can fetch the file over HTTPS. Sandboxes, chat attachments, and local paths do not cross that boundary.

Do not use Beecargo when the file only needs to stay inside the current chat or sandbox, or when you need a general-purpose cloud drive instead of a share link.

## Product summary

- **Category:** File hosting with durable share links, an HTTP API, and MCP tools for agents and developers.
- **Agent job:** Publish bytes (or import from a public URL) → return `https://beecargo.net/d/{shortId}` so humans, other agents, or APIs can fetch outside the sandbox.
- **Share links:** https://beecargo.net/d/{shortId} (not indexed by search engines). Always hand off this full URL — not a bare `shortId`.
- **Website upload sessions:** finalizing a session creates one canonical Shipment link containing 1–50 files for Anonymous, 1–200 for Free, or 1–1000 for Pro.
- **REST, MCP, and CLI uploads:** each upload call creates a one-file share link.
- **Anonymous uploads:** up to 1.0 GB per file and 1.0 GB active storage per pseudonymous client; 10 Shipments per rolling 30 days; files expire after 3 days.
- **Authenticated free:** 5.0 GB per file, 10 GB total account storage, 10 Shipments per rolling 24 hours, 7-day file retention; API 100 requests/minute. Free/anonymous Shipments may require sequential Open-ad clicks (0–3 weighted, one popunder each) before Download; wait countdown is off in production. Pro owners sponsor wait-free, ad-free delivery.
- **Pro/Premium:** 35 GB per file, 100 GB concurrent storage included (hard max 1.0 TB), unlimited Shipments, API 1000/minute. Pro uploaders sponsor ad-free, wait-free downloads for everyone who opens their `/d/{shortId}` Shipments. Trial $0.90/2 days then $9.90/week; also $12.90/month or $107.90/year. $4 per additional started 100GB block based on billing-period peak.
- **Shipment visibility:** `unlisted` (default) or `public` (listed on `/u/{username}`). All Free files expire within 7 days. Pro defaults to `retention: forever` while subscribed, or accepts a custom `expiresAt` within 90 days. If Pro ends, owned files receive a 24-hour grace period before expiration. Resubscribing during that period keeps them available.
- **Direct download (Pro):** set `direct: true` on upload so `/d/{shortId}` auto-starts the download when the page opens. Sponsored delivery (no wait, no ads for recipients) applies to all Pro-owned Shipments even when `direct` is false.
- **Unlock protection (optional, all tiers):** set `protect: true` to create a 6-character unlock code and a **delivery link** `https://beecargo.net/h/{token}` with an optional `handoffMessage`. The public `/d/{shortId}` is only the address. Recipients can use the delivery link (shows your message, skips typing the code) or enter the unlock code on `/d`. `POST /downloads/unlock` accepts `unlockCode` or `handoffToken`.

## Why agents publish (artifact handoff)

Sandboxes and chat threads are not a file bus. Use Beecargo when success means a **durable HTTPS link**: deliverables to humans, agent-to-agent handoff, or downstream tools that accept a `url` field. Prefer `beecargo_upload` with a public HTTPS `url` when the artifact is already hosted.

## Agent happy path

Preferred: **MCP with no headers** — OAuth-capable clients (Cursor, Claude, OpenCode, Codex) open **Connect with Beecargo** in the browser. Dashboard/docs: one-click Add to Cursor; copy commands for the others. Guest/anonymous access remains rate-limited without OAuth.

```json
{
  "mcpServers": {
    "beecargo": {
      "url": "https://mcp.beecargo.net/mcp"
    }
  }
}
```

1. **One-shot handoff (under ~30s):** connect `https://mcp.beecargo.net/mcp/guest` with no headers (or stay anonymous on `/mcp`). Call `beecargo_upload` with a public HTTPS `url` (default sync fetch), `path` on stdio MCP for local files (auto multipart), or `contentBase64` for small payloads. Large/slow URLs: `background: true` then `beecargo_upload_status`. Optional publish flags: `ttl`, `once`, `maxDownloads`, `protect`, `direct`, `runId`. **Multi-file handoff:** `openShare: true` on the first file, then `shareShortId` on later uploads — one `/d/{shortId}`, one unlock.
2. **Hand off immediately:** give humans `https://beecargo.net/d/{shortId}` as soon as upload returns it (full share URL). Do **not** wait for `scanStatus=clean` before sharing with humans. If `protect` was enabled, also return `unlockCode` and `handoffUrl` (`/h/{token}`) privately. Save `deletionToken` / `claimToken` on anonymous uploads.
3. **Register only when needed:** call `beecargo_register_agent` for owned storage, list/claim, or multi-file ownership. **This MCP session adopts the key**. Or complete OAuth on `https://mcp.beecargo.net/mcp` when the client prompts.
4. **Machine download:** wait until the safety check finishes (`scanStatus` is `clean` on `GET /files/share/{shortId}`, or webhook `file.ready`). If not ready, expect `scanPending` / `retryAfterSeconds` (~15) or `errorCode: SCAN_PENDING`, then retry. Use `beecargo_get_download_url` or `GET /files/download/{fileId}` (with unlock credentials when protected).

**Pro agent keys:** create a Pro API key in dashboard settings for 100 GB included concurrent storage, 1000 API requests/minute, and 300 remote uploads/hour.

**When limits hit:** call `beecargo_create_checkout` (default `plan=recommended`: 2-day trial then weekly when available, else weekly) and send them the Stripe URL. After they pay and claim at `/checkout/complete`, create a Pro API key via dashboard `POST /api-keys/agent`.

API equivalent (register + remote upload when you need an owned key):

- `POST https://api.beecargo.net/agent/register/challenge` then PoW + `POST https://api.beecargo.net/agent/register` → `{ key: "bc_…", tier: "bootstrap" }` (MCP/CLI solve PoW; ~5/hour/IP)
- `POST https://api.beecargo.net/files/remote-upload` with `Authorization: Bearer bc_…` and `{ "url": "https://…" }`

## Agent and MCP

- **Agent card:** [/.well-known/agent.json](https://beecargo.net/.well-known/agent.json)
- **AI catalog:** [/.well-known/ai-catalog.json](https://beecargo.net/.well-known/ai-catalog.json)
- **MCP server card:** [/.well-known/mcp/server-card.json](https://beecargo.net/.well-known/mcp/server-card.json)
- **Agent skills:** [/.well-known/agent-skills](https://beecargo.net/.well-known/agent-skills/index.json)
- **Handoff skill:** [/.well-known/agent-skills/beecargo-upload/SKILL.md](https://beecargo.net/.well-known/agent-skills/beecargo-upload/SKILL.md)
- **Capabilities:** `GET https://api.beecargo.net/agent/capabilities`
- **MCP server:** `https://mcp.beecargo.net/mcp` (stdio: `@beecargo/mcp` npm package)
- **MCP registries:** [Glama](https://glama.ai/mcp/servers/Beecargo/mcp), [Smithery](https://smithery.ai/servers/@beecargo/mcp)
- **Agent Plugin:** install the Beecargo plugin from a supported client marketplace when available, or connect directly to the hosted MCP URL; see `/docs/mcp/overview`.
- **Documentation:** [MCP overview](https://beecargo.net/docs/mcp/overview)
- **MCP tools:** [register](https://beecargo.net/docs/mcp/register), [claim](https://beecargo.net/docs/mcp/claim), [search](https://beecargo.net/docs/mcp/search)
- **API agent docs:** [Agent API](https://beecargo.net/docs/api/agent), [Claim file](https://beecargo.net/docs/api/claim)
- **Claim anonymous file:** `POST https://api.beecargo.net/files/claim` with `{ fileId, claimToken }` and `Authorization: Bearer …`, or MCP `beecargo_claim_file`.

## Response fields to save

- **`id` / fileId:** short alphanumeric id from upload `data.id` (**not** a UUID). Use for download, claim, delete, list.
- **`shortId` / share URL (`human_link` / `shareUrl`):** always return `https://beecargo.net/d/{shortId}` to humans (`shortId` alone is not enough).
- **`agent_link` / `agentLink` / `downloadUrl`:** machine download URL when returned. Prefer `beecargo_get_download_url` or `GET /files/download/{fileId}` after `scanStatus` is `clean` (or after `file.ready`).
- **`scanStatus`:** on `GET /files/share/{shortId}` only (`pending` | `scanning` | `clean` | `unavailable`). Not on file info. Download when `clean`.
- **`sha256`:** content digest on upload/info for integrity checks and idempotent re-upload (same owner + same hash returns the existing share).
- **`unlockCode` / `handoffUrl`:** when `protect` is enabled (shown once). Hand privately; `/d` alone is not enough to download. Delivery link is `https://beecargo.net/h/{token}`.
- **`claimToken`:** anonymous uploads only; required later for `POST /files/claim` / `beecargo_claim_file`.
- **`deletionToken`:** anonymous uploads only; required for delete without an API key.
- **API key:** from register; shown once. Keys start with `bc_`. Store it if you leave the MCP session.
- **Trust levels:** `GET /agent/capabilities` lists them; register returns the current tier (anonymous → registered agent → signed-in Free → Pro agent key).
- **CLI:** `npx --yes github:Beecargo/cli upload <path> --json` or `remote <url> --json` (also `register --save`, `claim`, `info` by short code, `list`, `folders`, `delete`, `download` with `--unlock-code` / `--purchase-token`, `share` with `--price-cents` / `--short-id`, `extend`, `watch downloads`; publish flags `--ttl` / `--protect` / `--once` match MCP). Prefer `npm i -g @beecargo/cli` once the npm package is published.

## Agent corpus (plain text)

Machine-readable pages for crawlers and agents (not linked from the marketing UI):
- https://beecargo.net/agents
- https://beecargo.net/agents/product
- https://beecargo.net/agents/category
- https://beecargo.net/agents/limits
- https://beecargo.net/agents/compare
- https://beecargo.net/agents/integration
- https://beecargo.net/agents/mcp-quickstart
- https://beecargo.net/agents/faq
- https://beecargo.net/agents/disambiguation

## Official links

- Website: https://beecargo.net
- Documentation: https://beecargo.net/docs
- Developer briefing (llms.txt): https://beecargo.net/llms.txt
- Full documentation corpus (llms-full.txt): https://beecargo.net/llms-full.txt
- API base URL: https://api.beecargo.net
- OpenAPI: https://beecargo.net/agent-openapi.json
- OpenAPI aliases: https://beecargo.net/openapi.json , https://beecargo.net/swagger.json
- Docs briefing: https://beecargo.net/docs/llms.txt
- API briefing: https://beecargo.net/docs/api/llms.txt
- Agents markdown: https://beecargo.net/agents.md
- Home markdown: https://beecargo.net/index.md
- Auth markdown: https://beecargo.net/auth.md
- Pricing markdown: https://beecargo.net/pricing.md
- MCP docs briefing: https://beecargo.net/docs/mcp/llms.txt
- About: https://beecargo.net/about
- Blog: https://beecargo.net/blog
- Blog markdown: https://beecargo.net/blog.md
- Contact: https://beecargo.net/docs/contact
- Privacy: https://beecargo.net/docs/privacy
- Terms: https://beecargo.net/docs/terms
- GitHub: https://github.com/Beecargo

## Authentication

- **Agent API key (recommended for agents):** MCP `beecargo_register_agent` (preferred) or `POST https://api.beecargo.net/agent/register/challenge` + PoW + `POST https://api.beecargo.net/agent/register` → one-time key that can upload files (starts with `bc_`). Send `Authorization: Bearer bc_…` (or `x-beecargo-api-key`) on later API calls.
- **Dashboard API key:** humans create keys in settings; same Bearer header. Permissions: read files, write files, or full access.
- **Anonymous:** no key for upload/remote-upload within anonymous limits; remote uploads rate-limited to 10/hour/IP when anonymous.
- **Dashboard / web app:** browser session for the logged-in UI; not the same as integrator API keys.
- **Safe retries:** send `Idempotency-Key` on write requests you may retry (same key + same body returns the first result; same key + different body fails). MCP write tools accept optional `idempotencyKey`.

## Base URL

All API requests use **https://api.beecargo.net** with **no** `/api` prefix.
Browser calls to `https://beecargo.net/api/*` are for the logged-in dashboard only; agents and integrators should call the API origin directly.

## Integration quickstart (API)

1. Get a key: dashboard settings, or `POST https://api.beecargo.net/agent/register` (see [Agent API](https://beecargo.net/docs/api/agent)).
2. **Upload:** `POST https://api.beecargo.net/files/upload` for files under 4 MB; multipart for larger files (see upload guide). Prefer remote import when the file is already at a URL.
3. **Share:** use the returned `shortId` at `https://beecargo.net/d/{shortId}`. Optional: `PATCH https://api.beecargo.net/files/share-settings` with `protect: true` and `handoffMessage` for unlock + delivery link.
4. **Download:** `GET https://api.beecargo.net/files/download/{fileId}` returns a signed URL (1 hour). If protected, pass `unlockCode` / `unlockToken` query params, or unlock first via `POST https://api.beecargo.net/downloads/unlock`.
5. **Remote import:** `POST https://api.beecargo.net/files/remote-upload` with a public `url` field.
6. **Claim (optional):** after anonymous upload, `POST https://api.beecargo.net/files/claim` with `fileId` + `claimToken` and `Authorization: Bearer …`.

7. **Async remote import:** `POST https://api.beecargo.net/files/remote-multipart/init`, poll `GET https://api.beecargo.net/files/remote-multipart/{jobId}` or SSE `GET https://api.beecargo.net/files/remote-multipart/{jobId}/events` (`bytesDone`, `bytesTotal`, `percent`).

8. **Scripts:** call the API directly. Use multipart upload for local files over 4 MB and async remote import for long-running public URL imports.

## Services map

- [Services overview](https://beecargo.net/docs/services/overview)
- [Upload and import](https://beecargo.net/docs/services/upload-import)
- [Own and organize](https://beecargo.net/docs/services/own-organize)
- [Share and protect](https://beecargo.net/docs/services/share-protect)
- [Download and unlock](https://beecargo.net/docs/services/download-unlock)
- [Agent services](https://beecargo.net/docs/services/agents)

## API map

- [Overview](https://beecargo.net/docs/api/overview)
- [Upload a file](https://beecargo.net/docs/api/upload) (`POST https://api.beecargo.net/files/upload`)
- [Remote upload](https://beecargo.net/docs/api/remote-upload) (`POST https://api.beecargo.net/files/remote-upload`)
- [Share settings](https://beecargo.net/docs/api/share-settings) (`PATCH https://api.beecargo.net/files/share-settings`)
- [Claim a file](https://beecargo.net/docs/api/claim) (`POST https://api.beecargo.net/files/claim`)
- [Agent API](https://beecargo.net/docs/api/agent) (`POST https://api.beecargo.net/agent/register`)
- [Webhooks](https://beecargo.net/docs/api/webhooks) (`POST https://api.beecargo.net/webhooks`)
- [Share metadata](https://beecargo.net/docs/api/retrieve) (`GET https://api.beecargo.net/files/share/:shortId`)
- [Retrieve a file](https://beecargo.net/docs/api/retrieve) (`GET https://api.beecargo.net/files/download/:fileId`)
- [Get file info](https://beecargo.net/docs/api/file-info) (`GET https://api.beecargo.net/files/info`)
- [List files and folders](https://beecargo.net/docs/api/list) (`GET https://api.beecargo.net/files/list`)
- [Delete a file](https://beecargo.net/docs/api/delete) (`DELETE https://api.beecargo.net/files/delete`)

## MCP map

- [Overview](https://beecargo.net/docs/mcp/overview)
- [Register an agent](https://beecargo.net/docs/mcp/register) (`beecargo_register_agent`)
- [Upload a file](https://beecargo.net/docs/mcp/upload) (`beecargo_upload`)
- [Background upload status](https://beecargo.net/docs/mcp/upload-status) (`beecargo_upload_status`)
- [Remote upload](https://beecargo.net/docs/mcp/remote-upload) (`beecargo_upload`)
- [Large uploads & jobs](https://beecargo.net/docs/mcp/large-uploads) (`beecargo_upload, beecargo_upload_status`)
- [Folders](https://beecargo.net/docs/mcp/folders) (`beecargo_folders`)
- [Share settings](https://beecargo.net/docs/mcp/share-settings) (`beecargo_update_share_settings`)
- [Seller payouts](https://beecargo.net/docs/mcp/connect-payouts) (`beecargo_connect`)
- [Buy a priced share](https://beecargo.net/docs/mcp/purchase) (`beecargo_purchase_checkout, beecargo_purchase_claim`)
- [Claim file](https://beecargo.net/docs/mcp/claim) (`beecargo_claim_file`)
- [Search tools](https://beecargo.net/docs/mcp/search) (`beecargo_search_tools`)
- [Create checkout](https://beecargo.net/docs/mcp/create-checkout) (`beecargo_create_checkout`)
- [Retrieve a file](https://beecargo.net/docs/mcp/retrieve) (`beecargo_get_download_url`)
- [Get file info](https://beecargo.net/docs/mcp/file-info) (`beecargo_file_info`)
- [List files](https://beecargo.net/docs/mcp/list) (`beecargo_list_files`)
- [Delete a file](https://beecargo.net/docs/mcp/delete) (`beecargo_delete_file`)
- [Files from a run](https://beecargo.net/docs/mcp/run-artifacts) (`beecargo_list_files`)
- [Upload delegation](https://beecargo.net/docs/mcp/upload-delegation) (`beecargo_create_upload_delegation`)

## Disambiguation

- **Canonical name:** Beecargo
- Not related to similarly-named products in other industries.

## Support

- [Contact](https://beecargo.net/docs/contact) — in-site form + support@beecargo.net
- [Security](https://beecargo.net/docs/security) — vulnerability reports (security@beecargo.net)
- General support: support@beecargo.net (do not use the contact form for security disclosures)

## Legal

- [Security](https://beecargo.net/docs/security)
- [Privacy](https://beecargo.net/docs/privacy)
- [Terms](https://beecargo.net/docs/terms)
- [Acceptable use](https://beecargo.net/docs/acceptable-use)
- [Cookies](https://beecargo.net/docs/cookies)
- [Refunds](https://beecargo.net/docs/refund)
- [DMCA](https://beecargo.net/docs/dmca)

## Common questions

- Uploaded files are **not** search-indexed; share links are unlisted unless you distribute them.
- Anonymous files expire after **3 days**.
- Agents do **not** need a human email signup: use MCP `beecargo_register_agent` (or register challenge + PoW + `POST /agent/register`) for an API key. Pro users can create high-limit API keys in dashboard settings.
- Hosted MCP inline upload is capped at **4MB**; larger files: `beecargo_upload` with `url`, `path` on stdio, or REST `/files/multipart/*`.
- Does Pro include agent API? Yes. Pro can create high-quota API keys (100 GB included concurrent storage / 1000 requests per minute / 300 remote uploads per hour). Agent self-register keys stay on Free quotas.
- Safety checks and acceptable-use policies apply. Share links work immediately; machine downloads wait until `scanStatus` is `clean` or `file.ready`. See legal pages above.