# Thunderclip — API & Agent Reference Ephemeral URL service. Upload content, get a short-lived link. Both humans and agents are first-class clients; this document is the single source of truth for the HTTP surface and is reachable at: - `https://thunderclip.com/api` (canonical) - `https://thunderclip.com/AGENTS.md` (alias, case-insensitive) - `https://thunderclip.com/llms.txt` (curated index — points back here) App base URL (dashboard, auth, API): `https://thunderclip.com` Clip content is served from a **separate domain**: `clip.lc`. Inert clips (text, JSON, images, media, binary) share the host `https://th.clip.lc/`; script-capable clips (HTML, SVG, XML, PDF, unknown types) each get their own isolated origin `https://.clip.lc/` (a random short host). Always use the `url` returned by the API — never construct clip URLs by hand. ## Quick orientation - **Humans**: visit the website, sign in with Enter ID, mint an API key from the dashboard, and use it as a Bearer token. - **Agents**: walk the [device flow](#device-flow) below to provision yourself an API key on the operator's behalf — no human credential ever passes through you. - **MCP-speaking clients (Claude Desktop, Cursor, Zed, …)**: install the [`@rac.so/thunderclip-mcp`](https://www.npmjs.com/package/@rac.so/thunderclip-mcp) stdio server and Thunderclip becomes a native tool — including uploads straight from disk, which is the only way to publish binary. Auth is still via a bearer token you mint once with the device flow. - **Either**: every authenticated request needs `Authorization: Bearer clip_`. Keys never expire on their own; revoke them from the dashboard or via API. --- ## Device flow RFC 8628 OAuth Device Authorization Grant. Designed for the case where an agent is acting on behalf of a human who has a browser nearby. The agent never sees the operator's IdP credentials; the operator never sees the agent's machine. Approval happens entirely on Enter ID (Thunderclip's identity provider), which hands the operator a short **completion code** to type back into the agent — this binds the approval to your specific flow and defeats device-code phishing. Three actors, four steps: ### 1. Agent: request a code ``` POST /auth/device Content-Type: application/json {"agent_label": "claude-code"} ``` `agent_label` is optional; if provided it labels the device in the operator's Enter ID device list. To also label the API key you receive, resend the same `agent_label` on the token poll (step 3). Response (200): ```json { "device_code": "", "user_code": "ABCD-EFGH", "verification_uri": "https://enterid.org/device", "verification_uri_complete": "https://enterid.org/device?code=ABCD-EFGH", "expires_in": 600, "interval": 5 } ``` Save the `device_code`. Print the `verification_uri` and `user_code` to the operator. The `verification_uri_complete` form is convenient when you can render a clickable link (or a QR code). `POST /auth/device` also accepts `application/x-www-form-urlencoded` for off-the-shelf OAuth clients. ### 2. Operator: visit the URL and authorise The operator visits `verification_uri` (on Enter ID), enters the `user_code`, signs in, and approves. Enter ID then shows them a **three-character completion code** and asks them to type it back into your agent. Collect that code from the operator — you will send it on the final poll. Thunderclip resolves the approved operator to an account with the same email-anchored find-or-create logic as a regular login — an existing account is reused, a brand-new operator gets one auto-provisioned — and binds the agent's key to it. ### 3. Agent: poll the token endpoint Poll with just the `device_code` until the operator has approved; then poll once more with the `completion_code` they gave you. ``` POST /auth/token Content-Type: application/json { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "", "completion_code": "" } ``` Poll every `interval` seconds (5s minimum). Possible responses: | HTTP | Body | Meaning | | ---- | ------------------------------------------------- | ------------------------------------------------------------------------------------ | | 200 | `{"access_token":"clip_…","token_type":"Bearer"}` | Operator finished. The token IS your long-lived API key. | | 400 | `{"error":"authorization_pending"}` | Operator hasn't approved yet — keep polling (without a completion code). | | 400 | `{"error":"completion_required"}` | Approved, but no valid completion code yet. Ask the operator for it, then poll once more. | | 400 | `{"error":"slow_down"}` | You polled before `interval` elapsed. Wait at least 5s before retrying. | | 400 | `{"error":"access_denied"}` | Operator denied, or a wrong completion code voided the flow. Stop; start over. | | 400 | `{"error":"expired_token"}` | TTL exceeded, already consumed, or unknown `device_code`. Stop; start over. | | 403 | `{"error":"signups_closed"}` | The operator authenticated, but has no Thunderclip account and new accounts are closed. Stop; retrying cannot help. | Like `/auth/device`, this endpoint accepts both JSON and form-urlencoded. ### 4. Agent: store and use the key Treat the returned `access_token` exactly like any other Thunderclip API key — long-lived, revocable, scoped to the operator's account. Future runs of the same agent should reuse the stored key rather than running the device flow again. --- ## MCP server (Claude Desktop / Cursor / Zed / …) If your runtime speaks the [Model Context Protocol](https://modelcontextprotocol.io), Thunderclip ships an official stdio server that turns the API into native tools — no curl, no remembering the request shape. ```bash npx -y @rac.so/thunderclip-mcp # served from npm ``` Wired into Claude Desktop: ```json { "mcpServers": { "thunderclip": { "command": "npx", "args": ["-y", "@rac.so/thunderclip-mcp"], "env": { "THUNDERCLIP_API_KEY": "clip_..." } } } } ``` Tools exposed: `clip_upload`, `clip_upload_from_disk`, `clip_read`, `clip_modify`, `clip_delete`, `clip_cell`. Because it runs on your machine it can read your filesystem, and `clip_upload_from_disk` is the reason to prefer it over the [hosted server](#mcp): it publishes a file without the bytes passing through the model's context, and it is the only path that carries binary at all — images, fonts, archives and PDFs cannot travel as text parameters. If you would rather not put the key in your client's config file (they end up in dotfile repos), leave `env` out and put the key on the first line of `~/.config/thunderclip/credentials`, or `%APPDATA%\thunderclip\credentials` on Windows. The environment wins if both are set. Auth is your device-flow-minted API key — the server is a thin passthrough over this same HTTP API and holds no rules of its own. Source: [github.com/Racso/thunderclip/tree/main/mcp](https://github.com/Racso/thunderclip/tree/main/mcp). --- ## Sign-in (humans) ``` GET /auth/enterid ``` [Enter ID](https://enterid.org) is the only identity provider. Top-level browser navigation only — this sets an HttpOnly session cookie scoped to thunderclip.com. The registered redirect_uri is `https://thunderclip.com/auth/enterid/callback`. After a successful dance the browser lands on `/dashboard`; after a failure, on `/login?auth_error=`. Sign-in is email-anchored: Thunderclip looks up accounts by the verified email address Enter ID reports. Enter ID itself offers a magic link, a passkey, or "Sign in with Google" — whichever you use, the same address lands you in the same Thunderclip account. Thunderclip's own GitHub and Google buttons were retired for exactly that reason; accounts created through them are reached by signing in with the same email. **New accounts are closed while Thunderclip is pre-launch.** An identity that verifies at Enter ID but has no Thunderclip account behind it is refused — `/login?auth_error=signups_closed` in the browser, `403 signups_closed` on the device flow — and nothing is created. Existing accounts sign in normally. --- ## Blobs (large files) A **blob** is a large inert file — a video, an installer, an archive — up to **5 GB**. It is a different noun from a clip and the differences are load-bearing: - Served from **one** public host, `https://big.clip.lc/.`, **straight from storage**. No Thunderclip code is on a blob's read path. Range requests work natively, so a video seeks properly when embedded in a page. - **Inert data types only.** Anything script-capable (HTML, SVG, XML) is refused with `415` — that rule is what makes one shared host safe. - **Never a folder member.** Folders hold clips. - **Bytes never cross the Thunderclip server.** You upload directly to storage with presigned URLs, which is why there is no way to create a blob from a request body. It comes off a disk or it does not exist. - **Costs 1 credit per 500 MB, rounded up.** A 2.2 GB blob is 5 credits; the cap bounds any blob at 10. Extending a lifetime or restoring a lapsed blob is charged the same way. - Default lifetime **7 days**. Upload is three calls. ### 1. Open the upload ``` POST /api/blobs?ext=&ttl=&recovery=1 Authorization: Bearer Content-Type: application/json { "size": 524288000 } ``` `size` is the total in bytes and is **required**. It is what you are charged on, so the account must be able to cover it — the call fails with `402` before anything moves otherwise. ```json { "id": "w1q2hj07sa7wr", "url": "https://big.clip.lc/w1q2hj07sa7wr.bin", "upload_id": "…", "part_size": 16777216, "part_urls": ["https://…", "…"], "part_urls_expire_in": 21600, "credits_charged": 1, "disable_at": "2026-09-20T00:00:00.000Z" } ``` ### 2. Send the parts `PUT` each slice of the file to its URL, in order, `part_size` bytes each (the last one is whatever remains). Keep the `ETag` response header from each. A part that fails can simply be re-PUT to the same URL — that is your resume. ### 3. Complete ``` POST /api/blobs//complete Content-Type: application/json { "parts": [ { "part_number": 1, "etag": "\"abc…\"" }, … ] } ``` The server asks storage how big the assembled object really is, **settles the difference against what you declared**, and publishes. `credits_settled` is positive if you under-declared and were charged more, negative if you over-declared and were refunded. Declaring far less than you upload does not save anything: if the real size costs more than you can cover, the blob is discarded and your credits returned (`402`). Same for anything over 5 GB (`413`). Nothing is lost that was ever public — a blob's URL is not real until this call returns. | HTTP | Meaning | | ---- | ------- | | `402` | Not enough credits for the declared size, or for the real one at completion. | | `409` | Already completed. | | `413` | Over the 5 GB cap. | | `415` | Script-capable type. Upload it as a clip. | | `502` | Storage would not open or assemble the upload. Nothing was published; retry. | ### Managing blobs ``` GET /api/accounts//blobs?state=enabled|disabled|all PUT /api/blobs/?ttl= extend, or restore a lapsed blob DELETE /api/blobs/ immediate and permanent ``` **Disable and restore are eventual, not instant.** A lapsed blob stops being served within a few minutes, and a restored one comes back on the same schedule and at the identical URL. This is deliberate: nothing about a blob's lifetime is enforced by code sitting on its read path, so the transition is carried out by a background sweep. What *is* guaranteed is that the edge cache can never outlive the blob's lifetime, because the cache lifetime is written onto the object from its disable time at upload. A disabled blob returns a plain `404`, not a `410` — there is no Thunderclip code there to say anything more specific. --- ## Upload ``` POST /api/ Authorization: Bearer clip_ X-Extension: ``` Thunderclip is **extension-first**, and a type is **mandatory** — every upload must declare its type explicitly. There is no silent fallback to binary; an upload with no type signal is rejected with `400`. Send one of: - **`X-Extension` header** (preferred), or **`?ext=`** query — the bare file extension that fits the content (e.g. `md`, `json`, `diff`, `html`, `png`). It drives both the stored MIME type and how the clip renders. For arbitrary bytes with no meaningful extension, use `bin`, `dat`, or `raw`. - **`X-Content-Type` header**, or **`?contentType=`** query — an escape hatch for an exotic MIME no extension maps to (e.g. `application/vnd.foo+json`). The ambient `Content-Type` request header is **ignored** for type resolution — clients auto-set it, so it's unreliable. Use `X-Content-Type` when you want to set a MIME explicitly. Optionally, also send **`X-Filename`** (or **`?filename=`**) — the real file name, used for `Content-Disposition` so downloads land under it instead of the clip's id. It does not affect the type; see [Download names](#download-names). Query parameters: - `ttl` — Time-to-live in minutes. Default: 1440 (1 day). Maximum depends on tier. - `ext` — Extension; same as the `X-Extension` header (the header wins if both are set). - `contentType` — Explicit MIME escape hatch; same as the `X-Content-Type` header. - `filename` — Download name; same as the `X-Filename` header. Optional. - `recovery` — Set to `1` (or send `X-Recovery: 1`) to give the clip a **recovery window**. Off by default. Free at upload. See [The recovery window](#the-recovery-window). - `cell` — Set to `1` (or send `X-Cell: 1`) to attach a **cell**, a tiny read/write storage slot bound to the clip. Costs one extra credit. See [Micro-persistence](#micro-persistence-cells). Response (201): ```json { "id": "7x4m9qk2trwbe", "url": "https://th.clip.lc/7x4m9qk2trwbe", "contentType": "text/plain; charset=utf-8", "extension": "txt", "filename": "notes.txt", "size": 42, "createdAt": "2026-05-24T12:00:00.000Z", "disableAt": "2026-05-25T12:00:00.000Z" } ``` `filename` is present only when one was sent. `disableAt` is when the clip stops being served — from that instant every URL for it returns `410`. A clip has three lifecycle states: **enabled** (publicly reachable), **disabled** (its TTL ran out; it is no longer served, listed, or editable), and **destroyed** (its row and bytes are freed). Today a clip is destroyed as soon as it is disabled, so `disableAt` is the only lifetime you need to track. Ids are 13 lowercase characters (Crockford base32: digits and letters minus `i l o u`). The `url` is canonical and depends on the clip's type class: - **Inert** types (text, markdown, JSON, CSV, source code, images, audio, video, binary, diffs) share the host: `https://th.clip.lc/`. - **Script-capable** types (`html`, `svg`, `xml`, `pdf`, and anything unknown) each get their own isolated origin: `https://.clip.lc/`, where `` is a random short label unique to that clip. Treat the returned `url` as opaque — don't derive it from the id. When you request a cell (`X-Cell: 1` / `?cell=1`), the response also carries `"cell": true` and a `"cellUrl"` pointing at the cell's read/write endpoint on the clip's own `clip.lc` host. ### Extensions with special rendering | Extension | Resolved type | Rendering | | ---------------- | ------------------ | ------------------------------------------- | | `diff` | `text/x-diff` | Syntax-highlighted unified diff | | `json` | `application/json` | Collapsible tree view | | `md` | `text/markdown` | Rendered markdown | | `html` / `htm` | `text/html` | Highlighted source (the file URL serves the live page) | | `svg` | `image/svg+xml` | Highlighted source (the file URL renders the image) | | `csv` / `tsv` | `text/csv` / TSV | Sortable table (rendered view only) | | `xml` | `application/xml` | Highlighted source (the file URL serves the XML) | | audio (see below) | `audio/*` | Player page with waveform (rendered view only) | | video (see below) | `video/*` | No page — both URLs serve the bytes | | code (see below) | per extension | Syntax-highlighted source with line numbers | | other | per extension | Raw content with the resolved MIME | Code files render as a highlighted, line-numbered page, dispatched by extension: `js`/`jsx`/`ts`/`tsx`, `py`, `rb`, `go`, `rs`, `java`, `kt`, `c`/`h`, `cpp`, `cs`, `php`, `swift`, `sh`/`bash`, `sql`, `yaml`/`yml`, `toml`, `ini`, `css`/`scss`/`less`, `lua`, `dockerfile`, `makefile`, `r`. Files over 512 KB are served raw instead. A file URL never highlights. Every page above is rendered in the reader's browser: the response is a small shell that fetches the clip's own raw URL and builds the view client-side. It needs JavaScript, and a document over 2 MB is served raw rather than given a viewer that would never finish painting. Audio extensions: `mp3`, `wav`, `ogg`/`oga`, `m4a`, `aac`, `flac`, `opus`, `weba`. The page URL serves a player with a click-to-seek waveform — something the browser can't give you, which is the test a viewer has to pass. Video (`mp4`/`m4v`, `webm`, `mov`, `mkv`) has **no page**: our player was a bare `