# 83blue transfer: complete API reference

Free, no-signup file transfer for AI agents and humans, at https://upload.83blue.com.
Upload a file, get a share url and a password, hand both to any other agent or person;
they download with one request. No accounts, no API keys, no cookies, no tracking.
Automated and bot use is welcome. Files are deleted automatically at expiry.

Limits:

- Max file size: 1 TB (chunked protocol); 512 MB in a single request; 100 MB per MCP call
- Retention: 1 to 180 days; default 180 (6 months) for HTTP uploads, 30 days for MCP tool calls
- Simultaneous uploads: 3 site-wide; when full the reply is HTTP 429 with a Retry-After
  header and a JSON error. Wait a few seconds and retry: it works like a queue.
- Download speed: 1 Mbit/s per connection after the first 512 KB, max 3 connections per IP.
  This service optimises for handoffs, not bulk transfer speed.
- Price: free, within fair use (no illegal content, no malware, not a CDN or permanent storage)

Tip: fetching https://upload.83blue.com/ with a curl or wget user agent returns plain-text
usage instructions instead of HTML.

## One-shot upload: POST /api/upload

For files up to 512 MB, one request.

Multipart style (form field `file`):

    curl -F "file=@report.zip" https://upload.83blue.com/api/upload

Raw-body style (PUT or POST, name in the query string or an X-Filename header):

    curl -T report.zip "https://upload.83blue.com/api/upload?name=report.zip"

Optional parameters (query string or form fields):

- `password`: custom password, 8-64 characters; a strong one is generated when omitted
- `expires_days`: 1 to 180, default 180
- `name`: file name for raw-body uploads

Response:

    {
      "ok": true,
      "token": "1f0c9a41c58a7b2d90aa",
      "url": "https://upload.83blue.com/d/1f0c9a41c58a7b2d90aa",
      "filename": "report.zip",
      "size": 18874368,
      "size_human": "18 MB",
      "expires_at": "2027-02-04T14:00:00+00:00",
      "downloads": 0,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "password": "Ab3k-Xy7q-Mn2p",
      "capability_url": "https://upload.83blue.com/f/1f0c9a41c58a7b2d90aa/KEY",
      "handoff_url": "https://upload.83blue.com/h/1f0c9a41c58a7b2d90aa/KEY",
      "download": {
        "api": "https://upload.83blue.com/api/download?token=1f0c9a41c58a7b2d90aa&password=Ab3k-Xy7q-Mn2p",
        "curl": "curl -fL -OJ \"https://upload.83blue.com/api/download?token=1f0c9a41c58a7b2d90aa&password=Ab3k-Xy7q-Mn2p\""
      },
      "handoff": "Give the receiving agent or person the url and the password. ..."
    }

Errors (JSON, `ok: false` with an `error` message): 400 bad request, 413 too large for a
single request (use the chunked protocol), 507 server out of space. Note: request bodies
over ~520 MB are rejected by the web server itself with a plain non-JSON 413.

## Download: GET /api/download

    curl -fL -OJ "https://upload.83blue.com/api/download?token=TOKEN&password=PASSWORD"

- `token` accepts the 20-character transfer id or the full share url
- Supports HTTP Range: interrupted downloads resume, download managers can segment
- Errors: 404 unknown or expired transfer, 403 wrong password
- The direct link https://upload.83blue.com/dl/TOKEN?p=PASSWORD also works, as does the
  human download page at https://upload.83blue.com/d/TOKEN

## Capability and handoff urls

Every upload response contains two urls that carry their whole secret (no password needed):

- `capability_url` (`/f/TOKEN/KEY`): GET downloads the raw file (HTTP Range works),
  DELETE removes the transfer immediately (`curl -X DELETE "$CAP"`).
- `handoff_url` (`/h/TOKEN/KEY`): GET returns a markdown briefing any model understands:
  what the transfer is, the file manifest for zip bundles, the root HANDOFF.md content,
  sha256, and exact download commands. `Accept: application/json` returns the same as
  structured data. This is the one url to paste into any chat with any model, from any
  provider: the receiving model fetches it and picks up the whole handoff in one go.

The handoff convention: put `HANDOFF.md` (or INSTRUCTIONS.md / README.md) at the root of
a zip bundle with a briefing for the next agent; the handoff url and the MCP receive_file
tool surface it before anything is downloaded.

Self-test in four commands:

    printf 'hello agent' > probe.txt
    CAP=$(curl -sS -F "file=@probe.txt" "https://upload.83blue.com/api/upload?expires_days=1" | jq -r .capability_url)
    curl -sS "$CAP" | sha256sum     # compare with .sha256 from the upload response
    curl -sS -X DELETE "$CAP"       # {"ok":true,"deleted":true}

## Metadata: GET /api/info

    curl "https://upload.83blue.com/api/info?token=TOKEN&password=PASSWORD"

Returns the same JSON shape as the upload response (filename, size, expires_at,
downloads, download commands) without touching the file.

## Chunked, resumable upload (files up to 1 TB)

1. `POST /api/create` with JSON body `{"name": "...", "size": bytes, "fingerprint": "64-hex"}`.
   The fingerprint is any 64-character hex string identifying the file, e.g. sha256 of
   "name|size". Optional: `password`, `expires_days`. Returns `{token, offset, password}`.
   Re-creating with the same fingerprint and size from the same IP resumes the unfinished
   transfer (offset > 0) instead of starting over; a fresh password is issued.
2. `POST /api/chunk?token=TOKEN&offset=OFFSET` with raw bytes in the body (chunks up to
   256 MB). Returns `{offset}`; on offset mismatch replies 409 with the real offset so you
   can re-sync; when the declared size is reached it replies `{"complete": true, "link": "..."}`.
3. `GET /api/status?token=TOKEN` returns the current offset at any time.

Example script:

    FILE="big.iso"
    SIZE=$(stat -c%s "$FILE")
    FP=$(printf '%s' "$FILE|$SIZE" | sha256sum | cut -c1-64)
    RES=$(curl -fsS -X POST https://upload.83blue.com/api/create \
      -H 'Content-Type: application/json' \
      -d "{\"name\":\"$FILE\",\"size\":$SIZE,\"fingerprint\":\"$FP\"}")
    TOKEN=$(echo "$RES" | jq -r .token); PASS=$(echo "$RES" | jq -r .password)
    OFFSET=$(echo "$RES" | jq -r .offset)
    while [ "$OFFSET" -lt "$SIZE" ]; do
      RES=$(dd if="$FILE" bs=1M skip=$((OFFSET / 1048576)) count=64 2>/dev/null \
        | curl -fsS -X POST --data-binary @- \
          "https://upload.83blue.com/api/chunk?token=$TOKEN&offset=$OFFSET")
      OFFSET=$(echo "$RES" | jq -r .offset)
    done
    echo "url: https://upload.83blue.com/d/$TOKEN  password: $PASS"

## MCP server

Endpoint (Streamable HTTP transport, JSON-RPC over POST, no authentication):

    https://upload.83blue.com/mcp

Setup:

- Claude Code: `claude mcp add --transport http transfer https://upload.83blue.com/mcp`
- claude.ai / Claude Desktop: Settings > Connectors > Add custom connector > paste the url
- Cursor (`~/.cursor/mcp.json`): `{ "mcpServers": { "transfer": { "url": "https://upload.83blue.com/mcp" } } }`
- VS Code (`.vscode/mcp.json`): `{ "servers": { "transfer": { "type": "http", "url": "https://upload.83blue.com/mcp" } } }`
- ChatGPT: Developer mode connector with authentication "No authentication" (paid plans)

Tools (the old names send_text, send_files and receive still work as aliases):

- `share_text {content, filename?, expires_days?, password?}`: upload text (instructions,
  code, JSON, a prompt for another model) as a downloadable file; returns handoff and
  capability urls plus a share url + password and a ready-made handoff message.
- `share_file {files: [{filename, content_text | content_base64}], bundle_name?,
  expires_days?, password?}`: upload up to 100 files in one call; two or more files are
  zipped into a single bundle server-side, so one url carries the whole handoff.
  100 MB decoded per call; use the HTTP API for bigger payloads.
- `share_conversation {transcript, files?, title?, expires_days?, password?}`: hand a
  whole working context to another model. The markdown transcript becomes HANDOFF.md at
  the root of a zip bundle together with the files; the returned handoff url is the one
  string to paste into any chat with any model.
- `receive_file {url_or_token, password?, max_inline_bytes?}`: fetch a transfer by
  capability url (no password needed) or share url + password; returns metadata with
  sha256, lists zip bundle contents, reads the root HANDOFF.md first, inlines text
  content up to max_inline_bytes (default 100 KB, max 1 MB), and otherwise returns the
  curl command to download.

## A2A (Agent2Agent protocol)

- Agent card: https://upload.83blue.com/.well-known/agent-card.json
- JSON-RPC endpoint: https://upload.83blue.com/a2a (protocol 0.3.0, message/send only,
  non-streaming; replies synchronously with a plain Message, never a Task)
- Share: send FileWithBytes parts (multiple files are zipped); a data part
  {"transcript": "..."} becomes HANDOFF.md at the root; optional expires_days/password.
- Fetch: send a data part {"url": "...", "password": "..."} or a FileWithUri pointing at
  this service. The reply carries metadata plus a FileWithUri capability url.
- This service is a natural host for the uri in any A2A FileWithUri part; the A2A
  specification deliberately leaves that hosting to external services.

## The agent handoff pattern

Agent A (any machine, model or chat session) uploads a bundle with everything the next
agent needs: instructions, code, data. Agent A then passes two strings to agent B through
any channel (chat message, ticket, e-mail, A2A message): the url and the password. Agent B
downloads with one request and gets to work. This replaces ad-hoc SSH routes, shared cloud
buckets and pasted-inline files. In Google's A2A protocol, a transfer url here works as the
uri in a FileWithUri part; the A2A specification deliberately leaves file hosting to
external services like this one.

Handoff message template (works with any model that can fetch a url):

    Pick up where I left off. Fetch this url for the full briefing and files:
    https://upload.83blue.com/h/TOKEN/KEY

Or, spelling everything out:

    I have uploaded a bundle for you on 83blue transfer.
    Download: curl -fL -OJ "https://upload.83blue.com/f/TOKEN/KEY"
    Unzip it and read HANDOFF.md first.

## Security

- HTTPS everywhere; 80-bit link tokens; separate ~70-bit auto-generated passwords stored
  only as bcrypt hashes; automatic deletion at expiry; no tracking or analytics.
- Anyone holding url + password can download until expiry: treat the pair as a secret.

## More

- Human docs: https://upload.83blue.com/docs
- OpenAPI 3.1: https://upload.83blue.com/openapi.json
- Short version: https://upload.83blue.com/llms.txt