Deploying

Query params: ttl, name & email

The deploy endpoint takes three optional query parameters — one controls how long a drop lives, one gives it a stable alias, and one mails the claim link to an address you choose. They're independent and combine freely: POST https://ship.page/deploy?ttl=3600&name=pr-42. Everything else about the request stays exactly as in the Quickstart.

?ttl=<seconds>

Sets the drop's time-to-live in whole seconds, counted from the moment the deploy lands. So ?ttl=900 publishes a drop that disappears after fifteen minutes — handy for one-look shares.

Minimum

60 seconds. Anything lower is rejected — see Errors.

Free plan

Capped at 30 days (2592000) anonymously, or 90 days (7776000) signed in. Larger values are rejected with a 400 — going past those caps needs a subscription.

Subscribers

Any value above the minimum — minutes, months, or years.

Omitted

Anonymous drops expire after the default 30 days, signed-in free drops after 90; subscriber drops never expire.

?name=<alias>

Instead of a random slug, the drop mounts at a name you choose — an address you can keep deploying to. PR previews, a living changelog, a status page: same URL, fresh content.

Availability

Subscriber-only — the request must carry an API key, see Authentication. Anonymous deploys always get a random slug.

Format

1–41 characters of [a-z0-9-], starting with a letter or digit. The odd cap keeps the combined subdomain label inside DNS's 63-character limit.

Reserved

-- may not appear anywhere in the alias — the double hyphen is the separator between your vanity subdomain and the name.

Redeploys

Posting again with the same name replaces the content in place. The URL stays exactly the same.

With the vanity subdomain acme claimed, a deploy named pr-42 lands here:

curl -X POST "https://ship.page/deploy?name=pr-42" \
-H "Authorization: Bearer sp_QffDmo0u…" \
-H "Content-Type: text/html" \
--data-binary @preview.html
# with the vanity sub "acme" claimed, this serves at:
# https://acme--pr-42.shipped.run/

?email=<address>

Anonymous deploys return a one-time claim token — and if that token is lost, the drop can never be attached to an account again. Pass an address here and the claim link lands in that inbox the moment the deploy does, so losing the token stops being fatal.

Availability

Anonymous deploys only. Authenticated deploys are owned by the account from the start — no claim token exists — so the param is ignored there.

Effect

One transactional email with the drop URL and its claim link, sent at deploy time. The address is stored on the drop, echoed back as claim_email in the deploy response, and never used for anything else. A redeploy clears it together with the old claim token.

Anti-abuse

An address receives at most 5 claim emails per day. Past that the deploy still succeeds — only the mail is skipped.