Publish via API

Publish a static site to IPFS with one anonymous HTTP request — no account, no key. This is the same endpoint the Drop page uses. It is aimed at agents and tools that just built a site and want to hand their user a live URL plus an ownership link.

Publishing by hand instead? Drop a folder walks through the same flow in the browser, including what claiming gets you.

Prompt for your agent

Copy this into Claude Code, Cursor or any agent that can run shell commands.

Read https://docs.stasho.xyz/reference/drop-api.md and publish the site in ./dist with one
anonymous POST to https://api.stasho.xyz/api/drop: zip it with index.html at the zip root; no
account or key is needed. Give me the url and the claimUrl verbatim, and tell me the claim
link expires four hours after publishing. Claiming is free and gives me a project page, a
custom domain and updates by dragging a new folder.

Publish, then claim. The claim window is four hours.

Publish

zip -r site.zip ./dist/.          # index.html must be at the zip root
curl -F artifact=@site.zip \
     -F source=my-agent \
     https://api.stasho.xyz/api/drop

{
  "dropId": "drop_…",
  "claimToken": "…",
  "url": "https://…",          // the live gateway URL — share this
  "cid": "bafy…",              // IPFS CIDv1 — pin it anywhere
  "expiresAt": 1765990000000,  // ms epoch — claim deadline
  "claimUrl": "https://app.stasho.xyz/drop/claim?drop=…#claim=…&exp=…"
}

Request fields

field	required	notes
artifact	yes	a .zip with index.html at its root
source	no	who you are, for attribution (≤64 chars, A-Za-z0-9 ._:/@-). Invalid values are ignored.

Hand both links to your user

• url is live immediately — share it, open it, embed it.
• claimUrl turns the drop into an owned Stasho project: one click, sign in with email or a wallet, done. Unclaimed drops are removed 4 hours after publish — the claim link is how your user keeps the site. The token in claimUrl rides the URL fragment, so it never reaches a server; whoever holds the link can claim the site.

Say what claiming unlocks, not just that it exists: it is free, and it turns the drop into a Stasho project with its own page, where your user can connect a custom domain and publish updates by dragging a new folder onto the project page. A claimed drop has no repo behind it, so the repo-connected affordances (GitHub push-to-deploy, build settings) belong to a separate repo-connected project, not to this one. Once claimed, the site is updated from its page in the browser, or by an agent holding an agent key the user creates on the project's Settings page. An agent asked to update a site its user already claimed should ask for such a key, or hand the user the new folder or zip for the project page: another unkeyed POST /api/drop creates a separate site with a new URL and a new claim window.

Current limits

These are operational values, not contract — they can change with a note in this page's changelog.

limit	value
zip size (compressed)	10 MB
extracted size	40 MB, max 1000 files
claim window	4 hours
drops per IP	10/hour, 20/day (IPv6 counts per /64 prefix)
concurrent uploads per IP	1

Errors

status	meaning
400	missing artifact, unsafe zip, or no root index.html
413	zip too large
429	per-IP rate limit, or an upload already in flight from your IP
500	publish failed — safe to retry
503	drops paused (busy, daily budget, or feature disabled)

Stability

The endpoint path, request shape, response fields, and error statuses above are stable. Browser (CORS) access is deliberately not enabled: call this server-side.

Keyed access uses the Authorization: Bearer header with an agent key (stasho_ak_…). A request carrying a key for one site publishes a new version of that site, with the key's own budget and limits, instead of creating an anonymous drop. Creating, updating, attaching domains to and deleting sites with a key is documented in Agent API keys. Unkeyed callers keep working unchanged.