pinthis.cloud

Documentation

How pinthis.cloud works

Everything on one page: the plans and their limits, the browser, the free names, the gateway, the Pinning Service API, and what runs underneath.

Plans and limits

A plan is three numbers and a switch.

  • Storage — how much you may keep pinned at once. Past it, new uploads are refused; nothing already stored is touched.
  • Devices — how many Wildroot installs (or other clients) may connect to the account.
  • Transfer allowance — how much moving data the plan pays for in a month. Storage hosts charge per byte moved; each plan covers a fixed amount. When it is used up, uploads and downloads pause until the month turns. Nothing is deleted, ever, for going over.
  • Public serving (Publish only) — how much the gateway will serve of your public pins in a month. Past it, your content is served slowly; well past it, the gateway answers 429 until the month turns. Still nothing is deleted.

The current numbers are on the plans list, which is read from the service itself. The free plan needs no sign-up: any Wildroot identity gets it on first contact, and a bigger free plan if the identity is a name.

Using it from Wildroot

Connect

Open Settings → Storage and choose pinthis.cloud. The browser signs one request with your identity key and the account is connected — there is no code to paste and no password. If you bought a plan on this site, import the name key that came with it first (below); the plan follows the key.

Back up

Choose a folder to keep. Wildroot seals every file on your device with a storage key that lives in its vault, then spreads the pieces across hosts. Neither we nor the hosts can open them. Restore from any device you have connected; if you lose every device, only a vault export can open the backup, so make one.

Keep online

On a Publish plan, publishing a site shows a Keep online box. Tick it and the site's archive is handed to our public account and registered: from then on it is served at https://pinthis.cloud/ipfs/<cid>/, stays available if your computer is off, and is provided to the IPFS network. Untick to stop; the last person to stop keeping a given archive online is the moment it is dropped.

The free name

Every payment on a paid plan — the first one and each monthly renewal — comes with one <label>.pinthis name. Choose the label at checkout or later from your account page.

The name is delivered as a key file, <label>.pinthis.hns-identity.json. Download it once: we hold the key only until you do, and forget it 14 days after issue if you never do (the name stays yours, you can ask for a new key from the account page). Add it in Wildroot under Your names → Add a key file… — or connect Wildroot storage from the browser’s Settings › Storage and claim the name there, in which case it is held in the browser the moment it is issued, no file to download. From then on the name is your sign-in here, and the plan you bought is attached to it.

Labels are 2–63 characters: letters, digits and hyphens, not starting or ending with a hyphen. A label already held as <label>.w3 on hns.one is reserved for its holder.

(?) What is the name, technically pinthis is a Handshake top-level name we hold; the labels under it are records in a zone we sign and serve, resolved in Wildroot like any other name. Nothing goes on a chain when a name is issued and there is no token behind it — the key file is the proof of control, and hns.one's registry keeps the binding between the key and the label. This is the same "no wallet, no tokens" path as hns.one's free names, and the same key file format.

A site at your name

On a Publish plan a name can point at one of your public pins — a folder with an index.html, or a single file. Pick it from the Names panel on the account page (or the → name link beside any pin), and the content is live at three addresses at once:

  • https://<label>.pinthis.cloud/ — for everyone, in any browser, with a certificate issued on first visit.
  • <label>.pinthis — in Wildroot, and any browser that resolves Handshake names. Wildroot reads the content natively over IPFS; other resolvers reach our gateway.
  • ipfs://<cid>/ and https://pinthis.cloud/ipfs/<cid>/ — the content itself, which never changes.

Repointing swaps the site in one step; the old content stays pinned until you remove it. Removing a pin a name points at detaches the name first, so an address never outlives what is behind it.

(?) What pointing writes Three records at <label>.pinthis in the zone hns.one signs: a TXT ipfs=<cid> that Wildroot resolves natively, a _dnslink TXT that gateways and kubo understand, and an A record for resolvers that only speak HTTP. The pinthis.cloud subdomain is the same content served by the gateway under that host.

Pinning from the account page

On a Publish plan the account page has a Pin something box. Two ways in:

  • Drop a file or a folder (or choose one). It is sent to us as-is, hashed into exactly the archive ipfs add --cid-version=1 would make — same chunking, same layout, so the CID you get is the one anyone else would compute — and pinned. A folder keeps its structure; its root is a directory, and …/ipfs/<cid>/ serves its index.html.
  • Paste a CID of something already on IPFS. We fetch it from public gateways and pin it, the same as a Pinning Service API request.

The address is shown the moment the upload lands; the pin itself takes a little longer (the page shows waiting → pinning… and then moves it into the public list). Anything that fails says why, and can be dismissed.

The same thing from a shell, with the account page's API token — one file per call, the body is the file:

with curl
curl -T photo.jpg -H "Authorization: Bearer <token>" \
  "https://pinthis.cloud/api/upload?name=holiday&filename=photo.jpg"

Folders go in three calls: POST /api/uploads {"folder":true} opens a session, PUT /api/uploads/<id>/files/<path> sends each file, POST /api/uploads/<id>/finish hashes and queues it. An open session lives six hours; the bytes count against the plan's storage as they arrive.

The gateway

Public pins are served at https://pinthis.cloud/ipfs/<cid>[/path]. It is a standard IPFS gateway for the content it holds:

  • Paths inside a directory resolve; a directory serves its index.html.
  • Range requests work, so video seeks and resumed downloads work.
  • Trustless forms: ?format=raw (one block) and ?format=car (the whole archive, or &dag-scope=block), also by Accept header. Responses carry X-Ipfs-Roots and are cached as immutable.
  • Content we do not hold is a 404; we do not fetch from the wider network on request.

Bytes served are counted to the pin's owner, against the plan's public serving allowance.

Finding it by CID

Anything pinned here is on IPFS the ordinary way: our node announces every block to the DHT and serves it over bitswap, so a CID that only we hold resolves from ipfs.io, Brave, or your own kubo with nothing configured. Bytes fetched this way count like any other byte served.

There is also the standard delegated routing API: GET https://pinthis.cloud/routing/v1/providers/<cid> answers with one provider — this gateway, over HTTP — for anything pinned here, and 404 otherwise. A node with HTTP retrieval (kubo 0.35 or later, ipfs config Routing.DelegatedRouters '["https://pinthis.cloud"]' and HTTPRetrieval.Enabled true) reads the blocks straight from the gateway and checks every hash itself, without a DHT lookup. Wildroot's built-in node is set up this way.

Pinning Service API

The Publish plan includes the IPFS Pinning Service API at https://pinthis.cloud/pins, so tools you already use can pin to us. Create a token on your account page (it is shown once).

with kubo
ipfs pin remote service add pinthis https://pinthis.cloud <token>
ipfs pin remote add --service=pinthis --name="my site" <cid>
ipfs pin remote ls --service=pinthis --status=queued,pinning,pinned
with curl
curl -X POST https://pinthis.cloud/pins \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"cid":"<cid>","name":"my site"}'

A request goes queued → pinning → pinned, or failed with the reason in info. We fetch the content as an archive from public gateways (trustless-gateway.link, ipfs.io, dweb.link), so it must be reachable through them when you ask — a node that is providing it to the network, or a gateway that already has it. Once pinned it is served by us as above. Deleting the request drops our copy unless someone else keeps the same content online.

The signed API (for apps)

Wildroot talks to the service with signed requests rather than cookies: an Authorization: Nostr <base64 event> header in the NIP-98 form, signed by the identity key. The signed u tag is the full URL including the query string; the payload tag is the SHA-256 of the body; an event is good for one use and sixty seconds.

  • POST /api/connect {responseUrl} — approve a pending connection from a client that talked to https://indexer.pinthis.cloud.
  • GET /api/me — the plan and where the account stands in it.
  • GET /api/pins, POST /api/pins {cid, shareUrl, name}, DELETE /api/pins/<cid> — public pins from an archive the client already holds (a share link to it).
  • GET /api/plans — public; what the plans list reads.

Any key can call these. A key that has never been seen becomes a free account; a key the hns.one registry vouches for as a name gets the name plan.

Billing

Plans are monthly subscriptions paid by card through Stripe; we never see the card number. Change the card, download invoices or cancel from the billing portal on your account page. A cancelled plan runs to the end of the paid month, then drops to the free plan: what fits the free plan stays, nothing new fits until it does, and your name stays yours. Sign-in to this site is by a one-time link to the email you paid with; Wildroot users never need it.

What runs underneath

Storage is the Sia network: independent hosts, paid per byte stored and moved, holding erasure-coded pieces of sealed files. We run an indexer — the coordinator that finds hosts, forms contracts and pays them — built on the Sia Foundation's indexd with our additions for per-account transfer metering. Data stored through us is in the same format the official Sia app uses and opens there. We also run the public gateway, the Pinning Service API and this site, on one server. Names are Handshake names under the pinthis top-level name, served by hns.one's registry. The service is open source; the browser is Wildroot.