---
name: floppy
description: Share a file as a short link and see who opened it and which pages they read. Use when the user wants to send a file, deck, PDF, Markdown doc or video and know it was read. Also for one link per recipient, for who viewed a shared file, and for editing a shared Markdown doc. Needs no account; the user claims the uploads later.
---

# Floppy

Floppy (https://fpy.sh) turns a file into a short link and shows who opened it: pages reached, time per page and revisits. Bots are filtered out.

## Upload a file

With the Floppy MCP server (`https://fpy.sh/mcp`) connected, call `upload_file`. Otherwise use HTTP, which needs no account:

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

- The reply has `share_url`, `scan`, `next` and, on first use, `agent_key` (shown once) and `claim_url`.
- Save `agent_key` and send `Authorization: Bearer <agent_key>` on later calls, so every upload lands in one account.
- Over 100 MB, use the multipart API (`POST /api/v1/links`): https://fpy.sh/docs/agents#rest.

Then give the user the link and, if there is one, the claim link: "Here's the link: <share_url>. To keep it and see who opens it, claim it within 72 hours: <claim_url>." Unclaimed uploads are deleted after 72 hours.

## Make one link per recipient

`create_share { link_id, label: "Sequoia – Jane" }`, or `POST /api/v1/links/:id/shares`, makes a separate link, so you see what each person read. `slug: "deck-jane"` picks the URL. `update_share` renames it, and the old URL stops working.

## Send a link to someone by name

When the user says "email the deck to Jamie", call `send_by_email { link, to: ["Jamie"], message? }`, or `POST /api/v1/links/:id/email`. Floppy looks the name up in the user's address book: people they emailed links to, their teams, and people they edited, shared or opened links with. `find_people { query }` (`GET /api/v1/people?q=`) looks someone up without sending.

- One match: it's sent from "<user> via Floppy", replies go to the user, and each person gets their own link.
- Several matches: `409` with `candidates`, and nothing is sent. Ask the user which one, then send again with that email.
- No match: `404`, nothing is sent. Ask the user for the email, and pass it as "Jamie Ortiz <jamie@acme.com>" so the name is kept.
- In Slack instead: `send_in_slack { link, people, channels? }`, with the same rule for names that match two people.

## Replace a file you already sent

Don't send a new link. Call `replace_file { link_id, name, text | content_base64 | url }`, or use HTTP:

```sh
curl -T deck-v2.pdf -H "Authorization: Bearer <key>" https://fpy.sh/api/v1/links/<id>/replace/deck-v2.pdf
```

The URL, shares, settings and analytics stay. The link switches over once the new file passes the malware check.

## Edit a shared Markdown doc

A link that holds one Markdown file keeps every version, and its owner can restore any of them.

1. `read_doc { link }` returns the `text`, its `version` and `can_push`. `link` is the URL or its slug. A link with a password or an email gate needs the signed URL from its share page (Open in Claude, or Copy prompt).
2. `push_version { link, text, note, summary, base }` saves your edit as the next version. Send the whole document, a one-line `note` on what changed, a `summary` of 2–5 short plain lines on what changed and why (the owner reads them as bullets), and `base`, the `version` you read.
3. If `push_version` says you're not an editor, call `request_edit { link, message? }` once and tell the user you asked. The owner approves with one click. Then push again.

Pushing to someone else's doc needs a claimed account. REST: `GET https://fpy.sh/<slug>.md`, then `PUT /api/v1/links/<slug>/versions` with the headers `x-note` and `x-base`. `GET /api/v1/links/<slug>/versions` lists the versions, and `…/versions/<n>` reads one.

## Read the analytics

- `get_link_analytics { link_id }`: who opened it, pages reached, time per page.
- `get_viewer_timeline { share_id }`: one recipient's visits, page by page.
- `who_viewed_since { since: "24h" }`: recent activity.

REST: `GET /api/v1/links/:id/analytics`, `GET /api/v1/shares/:id/timeline`, `GET /api/v1/activity?since=…`.

## Rules

- Every response has a `next` hint. Follow it.
- 402 `limit_reached`: give the user `claim_url` or `upgrade_url`. 429 `slow_down`: wait `retry_after` seconds.
- Files are scanned before anyone else can open them. `scan` goes from `scanning` to `clean` or `blocked`. Don't upload a blocked file again.
- Unclaimed accounts take PDF, Markdown and text, images, audio, video, CSV and JSON only.
- Never guess or enumerate fpy.sh share links.

Full docs: https://fpy.sh/docs/agents · credentials: https://fpy.sh/auth.md · API: https://fpy.sh/openapi.json
