# Beecargo

> Freemium file hosting: upload files, share via short links, and integrate with a REST API and MCP tools for AI agents. 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 REST) — you can ship without a human dashboard account.
2. Read **Authentication** and **Response fields to save** so you keep the right tokens.
3. Use **API map** / **MCP map** for parameters; fetch [llms-full.txt](https://www.beecargo.net/llms-full.txt) for full page text. Interactive OpenAPI: [Swagger](https://api.beecargo.net/docs).

## Product summary

- **Category:** Simple cloud file hosting with share links and a developer REST API.
- **Share links:** https://www.beecargo.net/d/{shortId} (not indexed by search engines).
- **Anonymous uploads:** up to 25 GB per file; direct uploads expire after 15 days; remote uploads after 7 days.
- **Authenticated free:** 5.0 GB account storage; API 100 requests/minute.
- **Premium:** higher API rate (1000/min), more storage, ad-free downloads. Pricing from $0.90/2 days trial, $12.90/month, $59.90/year.
- **Multipart threshold:** files ≥ 4 MB use multipart upload (see upload guide).

## Agent happy path

Preferred: **MCP with no headers** (hosted MCP is open by default; rate-limited).

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

1. Connect to `https://mcp.beecargo.net/mcp` (no `Authorization` / API key headers required).
2. Call `beecargo_register_agent` → bootstrap `bc_*` (`files_write`, free-tier quotas). **This MCP session adopts the key** for list/claim/owned uploads.
3. Call `beecargo_remote_upload` with a public HTTPS `url` (preferred; server streams to R2) or `beecargo_upload_file` for base64 under 4MB. Large local blobs: `beecargo_multipart_*`. Async remotes: `beecargo_remote_multipart_*`.
4. Give humans the share link `https://www.beecargo.net/d/{shortId}` from the response.

Anonymous-only (no register): same upload tools without a key — stricter TTL/limits; you **must** save `deletionToken` and `claimToken`.

**Premium agent keys:** dashboard `POST /api-keys/agent` (Premium required) or operator `POST /agent/api-keys` → 100GB storage, 1000 API/min, 300 remote/hour.

REST equivalent of steps 2–3:

- `POST https://api.beecargo.net/agent/register` → `{ key: "bc_…", tier: "bootstrap" }` (rate-limited per 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://www.beecargo.net/.well-known/agent.json)
- **Capabilities:** `GET https://api.beecargo.net/agent/capabilities`
- **MCP server:** `https://mcp.beecargo.net/mcp` (stdio: `@beecargo/mcp` npm package)
- **Docs:** [MCP overview](https://www.beecargo.net/docs/mcp/overview)
- **MCP tools:** [register](https://www.beecargo.net/docs/mcp/register), [claim](https://www.beecargo.net/docs/mcp/claim), [search](https://www.beecargo.net/docs/mcp/search)
- **API agent docs:** [Agent API](https://www.beecargo.net/docs/api/agent), [Claim file](https://www.beecargo.net/docs/api/claim)
- **Claim anonymous file:** `POST https://api.beecargo.net/files/claim` with `{ fileId, claimToken }` and Bearer `bc_*`, or MCP `beecargo_claim_file`.
- **Operator provisioning:** `POST /agent/api-keys` with `Authorization: Bearer <AGENT_PROVISIONING_SECRET>` for batch minting.
- **Operator lockdown:** `BEECARGO_MCP_REQUIRE_AUTH=true` + `BEECARGO_MCP_BEARER_TOKEN` on the MCP host requires transport bearer or `bc_*` on `/mcp`.

## 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:** `https://www.beecargo.net/d/{shortId}` for humans.
- **`claimToken`:** anonymous uploads only — required later for `POST /files/claim` / `beecargo_claim_file`.
- **`deletionToken`:** anonymous uploads only — required for delete without an API key.
- **`bc_*` key:** from register — shown once; store if you leave the MCP session.

## Agent corpus (plain text)

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

## Official links

- Website: https://www.beecargo.net
- Documentation: https://www.beecargo.net/docs
- Developer briefing (llms.txt): https://www.beecargo.net/llms.txt
- Full documentation corpus (llms-full.txt): https://www.beecargo.net/llms-full.txt
- API base URL: https://api.beecargo.net
- OpenAPI / Swagger UI: https://api.beecargo.net/docs
- OpenAPI JSON: https://api.beecargo.net/docs-json
- Agent OpenAPI: https://www.beecargo.net/agent-openapi.json

## Authentication

- **Agent machine key (recommended for agents):** `POST https://api.beecargo.net/agent/register` or MCP `beecargo_register_agent` → one-time `bc_*` with `files_write`. Send `Authorization: Bearer bc_…` (or `x-beecargo-api-key`) on later REST calls.
- **Dashboard API key:** humans create keys in settings; same Bearer header. Scopes: `files_read`, `files_write`, `full`.
- **Anonymous:** no key for upload/remote-upload within anonymous limits; remote uploads rate-limited to 10/hour/IP when anonymous.
- **Dashboard / web app:** Supabase session JWT (browser); not the same as integrator API keys.

## Base URL

All Nest API requests use **https://api.beecargo.net** with **no** `/api` prefix.
The Next.js site rewrites browser `https://www.beecargo.net/api/*` to the API for logged-in dashboard clients only.

## Integration quickstart (REST)

1. Get a key: dashboard settings, or `POST https://api.beecargo.net/agent/register` (see [Agent API](https://www.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://www.beecargo.net/d/{shortId}`.
4. **Download:** `GET https://api.beecargo.net/files/download/{fileId}` returns a signed URL (1 hour).
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 Bearer `bc_*`.

## API map

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

## MCP map

- [Overview](https://www.beecargo.net/docs/mcp/overview)
- [Register agent](https://www.beecargo.net/docs/mcp/register) — `beecargo_register_agent`
- [Claim a file](https://www.beecargo.net/docs/mcp/claim) — `beecargo_claim_file`
- [Search tools](https://www.beecargo.net/docs/mcp/search) — `beecargo_search_tools`
- [Upload a file](https://www.beecargo.net/docs/mcp/upload) — `beecargo_upload_file`
- [Remote upload](https://www.beecargo.net/docs/mcp/remote-upload) — `beecargo_remote_upload`
- [Retrieve a file](https://www.beecargo.net/docs/mcp/retrieve) — `beecargo_get_download_url`
- [Get file info](https://www.beecargo.net/docs/mcp/file-info) — `beecargo_file_info`
- [List files](https://www.beecargo.net/docs/mcp/list) — `beecargo_list_files`
- [Delete a file](https://www.beecargo.net/docs/mcp/delete) — `beecargo_delete_file`

## Disambiguation

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

## Legal

- [Privacy](https://www.beecargo.net/docs/privacy)
- [Terms](https://www.beecargo.net/docs/terms)
- [Acceptable use](https://www.beecargo.net/docs/acceptable-use)
- [DMCA](https://www.beecargo.net/docs/dmca)

## Common questions

- Uploaded files are **not** search-indexed; share links are unlisted unless you distribute them.
- Anonymous direct uploads expire after **15 days**; anonymous remote uploads after **7 days**.
- Agents do **not** need a human email signup: use MCP register or `POST /agent/register` for a bootstrap `bc_*` key. **Premium** unlocks high-limit agent keys via `POST /api-keys/agent`.
- MCP base64 upload is capped at **4MB**; larger files: `beecargo_remote_upload`, `beecargo_multipart_*`, or REST multipart.
- Does Premium include agent API? Yes — Premium can mint durable high-quota `bc_*` keys (100GB / 1000rpm / 300 remote/hr). Bootstrap self-register keys stay on free quotas.
- Malware scanning and acceptable-use policies apply; see legal pages above.