AGENT DOCS

CONNECT YOUR AGENT

Set up Floppy (https://fpy.sh) for me, so you can share files as short links and tell me who opened them.

1. Read https://fpy.sh/skill.md to learn how Floppy works.
2. Write a short hello.md and upload it with no account: curl -T hello.md https://fpy.sh/api/drop/hello.md
   The JSON reply has share_url, agent_key (shown once) and claim_url. Keep agent_key private: don't echo it back, commit it, or write it into a file inside a repo.
3. Connect the Floppy MCP server at https://fpy.sh/mcp with that key, the way your tool adds MCP servers (replace <agent_key>):
   - Claude Code: claude mcp add --transport http --scope user floppy https://fpy.sh/mcp --header "Authorization: Bearer <agent_key>"
   - Codex: add [mcp_servers.floppy] with url = "https://fpy.sh/mcp" and bearer_token_env_var = "FLOPPY_API_KEY" to ~/.codex/config.toml, and export FLOPPY_API_KEY in my shell profile
   - Cursor: add "floppy": { "url": "https://fpy.sh/mcp", "headers": { "Authorization": "Bearer <agent_key>" } } under mcpServers in ~/.cursor/mcp.json
   - Anything else, or if you can't add MCP servers: use HTTP with the same header, e.g. curl -T notes.md https://fpy.sh/api/drop/notes.md -H "Authorization: Bearer <agent_key>"
4. If you support skills or saved instructions, save https://fpy.sh/skill.md as one so you remember Floppy next time (Claude Code: ~/.claude/skills/floppy/SKILL.md).
5. Give me the share_url and the claim_url, and tell me to open the claim link and sign in with Google within 72 hours so the files stay in my account. If the MCP server only loads after a restart, tell me to restart.

QUICKSTART

No account, no key. Send the file's bytes with PUT:

curl -T deck.pdf https://fpy.sh/api/drop/deck.pdf

The filename at the end of the URL is the name people see. Optional query parameters: expiry (for example 1D, 3D) and label (for example Sequoia – Jane).

To keep every upload in one account, send the agent_key from your first response on every later call:

curl -T notes.md https://fpy.sh/api/drop/notes.md -H "Authorization: Bearer fpy_live_…"

Files over 100 MB don't fit in one request. Use the multipart flow (POST /api/v1/links, then PUT each part, then POST …/complete) with your key, or upload_file over MCP, which returns a multipart plan for big files.

WHAT YOU GET BACK

{
  "link": {
    "id": "q7f2m9x4k1ab",
    "name": "deck.pdf",
    "url": "https://fpy.sh/k3x9",
    "slug": "k3x9",
    "kind": "pdf",
    "size": 4404019,
    "status": "ready",
    "scan": "scanning",
    "created_at": "2026-11-06T12:03:00.000Z",
    "expires_at": "2026-11-09T12:03:00.000Z",
    "shares": 0,
    "views": 0,
    "via_agent": true
  },
  "share": null,
  "share_url": "https://fpy.sh/k3x9",
  "analytics_url": "https://fpy.sh/api/v1/links/<id>/analytics",
  "claim_url": "https://fpy.sh/claim/7f3c…",
  "agent_key": "fpy_live_…",
  "scan": "scanning",
  "limits": { "storageBytes": 1073741824, "maxFileBytes": 1073741824, "maxExpiryDays": 3, "maxLinks": 20, "expires_in_hours": 72 },
  "next": "Share the share_url. Your human can claim these files at https://fpy.sh/claim/7f3c… within 72 hours."
}

• share_url is the link to send. It works at once; while scan is scanning, visitors see "Checking file…" and the file opens when the scan is clean.
• agent_key is shown once. Save it and send it as Authorization: Bearer … on later calls so your uploads stay together. claim_url and agent_key only appear when Floppy created a new unclaimed account for you.
• claim_url is for your human. Give it to them with the link.
• scan is one of uploading, scanning, clean, blocked or unscanned-large.
• next is one plain sentence telling you what to do or tell your human. Every response has one.

CLAIMING

An upload without an account goes into an unclaimed account. It lasts 72 hours. Tell your human, in your own words:

I uploaded your file to Floppy: https://fpy.sh/k3x9. To keep it and see who opens it, claim it within 72 hours: https://fpy.sh/claim/7f3c…

• Opening the claim link means signing in with Google. Everything the agent made moves to that person's account: links, files, folders and view history. It works for a new or an existing Floppy account.
• The claim link works once and expires with the unclaimed account. Lost it? Call GET /api/v1/claim with your agent key, or the get_claim_link MCP tool.
• After the claim, your agent key keeps working, but it stays limited to the links it created (scope own). It can't see the human's other links. The human can widen it to the whole account at https://fpy.sh/app/keys.
• Nothing is claimed after 72 hours? The links stop working and every file is deleted.
• Unclaimed accounts can't pay. The claim page also offers "Claim and upgrade", which goes to checkout after sign-in.

MCP

Every tool returns its result plus a next hint.

REST API

Base URL https://fpy.sh. Auth is Authorization: Bearer fpy_live_… (or the dashboard's session cookie). JSON in and out. The full schema is at https://fpy.sh/openapi.json.

API keys are created and revoked by a signed-in human at https://fpy.sh/app/keys (/api/v1/tokens takes a session, never a key). Keys have access read, write or both, and scope account (everything) or own (only the links the key created).

LIMITS & ERRORS

A single drop or inline upload is also capped at 100 MB per request; use multipart above that. Unclaimed accounts can upload safe file types only (see Safety).

Every error has the same shape. next says what to do, and docs links here:

{
  "error": {
    "code": "limit_reached",
    "message": "This unclaimed account has used its 1 GB.",
    "claim_url": "https://fpy.sh/claim/7f3c…",
    "next": "Ask your human to claim this account at https://fpy.sh/claim/7f3c…. Claiming unlocks Free limits and lets them upgrade.",
    "docs": "https://fpy.sh/docs/agents#errors"
  }
}

SAFETY

• Every file is scanned before anyone but its owner can open it. Uploads start as scanning; the share page shows "Checking file…" until the verdict is in. Blocked files are never served.
• Executables and installers are blocked on every plan. Unclaimed accounts can upload only PDF, Markdown and text, images, audio, video, CSV and JSON. No archives, HTML or SVG.
• HTML and SVG are always downloaded, never rendered as a web page on fpy.sh.
• Bots are filtered. Email security scanners, link previews and datacenter traffic are kept apart and never counted as views.
• Share links are private. They belong to the people who made them. Never guess, enumerate or crawl fpy.sh links.
• Report abuse with the Report link on any share page.

TROUBLESHOOTING

• 401 on every call. The header must be exactly Authorization: Bearer fpy_live_…, with one space and no quotes. Keys revoked at https://fpy.sh/app/keys stop working at once.
• The client doesn't show Floppy's tools. Restart the client after adding the server, then sign in again (/mcp in Claude Code, codex mcp login floppy in Codex, Connect in Cursor).
• Sign-in loops or fails. Use the Google account you want the files in. Blocked pop-ups stop the OAuth window; allow them for the client.
• ChatGPT can read but not upload. Your plan only allows read access to custom MCP servers. Use another agent, or the curl call.
• The file is stuck on "Checking file…". Scans usually take seconds; large files take longer. Poll GET /api/v1/links/:id and look at scan.
• 402 limit_reached. Hand your human the claim_url or upgrade_url from the error. Paying or claiming lifts the limit for the same key at once.
• 413 on a drop. The file is over 100 MB. Use the multipart flow.
• I lost the agent key. It can't be shown again. If the account is unclaimed, start a new drop; if it was claimed, your human can make a new key at https://fpy.sh/app/keys.
• The claim link expired. After 72 hours unclaimed uploads are deleted. Upload again and pass the new claim link on sooner.

MORE PAGES

Setup for one tool at a time, with things to ask and an FAQ. Each page is also available as Markdown (add .md).

• Share files from Claude Code (Markdown)
• Share files from Claude (Markdown)
• Share files from ChatGPT (Markdown)
• Share files from Cursor (Markdown)
• Share files from Codex (Markdown)
• Share files from VS Code and GitHub Copilot (Markdown)
• A file sharing MCP server (Markdown)

How Floppy compares with other ways to share files:

• Floppy vs Papermark (Markdown)
• Floppy vs DocSend (Markdown)
• Floppy vs WeTransfer (Markdown)
• Floppy vs Dropbox (Markdown)
• Floppy vs Google Drive (Markdown)
• Floppy vs Smash (Markdown)
• Floppy vs Box (Markdown)