Deploying

Query params: ttl, name, email & agent

The deploy endpoint takes four optional query parameters: one controls how long a drop lives, one gives it a stable alias, one mails the claim link to an address you choose, and one names the agent that's publishing. 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.

On this page

?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:

bash

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.ship.place/

?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.

?agent=<name>

The name of the AI agent or app doing the publishing, like ?agent=claude. It doesn't change the deploy itself.

AI agents: this is required; e.g. ChatGPT, Claude, Cursor.

Format: Free text, up to 64 characters. Stored trimmed and lowercase, so ChatGPT becomes chatgpt. An empty value counts as not sent.
Availability: Every deploy, anonymous or authenticated. The MCP deploy_html and deploy_files tools take it as an agent argument.
Redeploys: The value from the deploy that created the drop sticks; redeploying a named drop doesn't overwrite it.

Last updated Jun 12, 2026