For makers

Ship API

Create, version, roll back, delete, and report shipped items over HTTP — from a script, a CI step, or an agent.

Updated June 11, 2026

Base URL and auth

All endpoints currently live under https://shippie.app/api/drops for compatibility. Creating a shipped item works with no auth at all (anonymous items, lower limits and a 24-hour cap). Sign requests with a Bearer API token to own the item, raise the limits, and keep it for up to 7 days: send the header Authorization: Bearer <token>. A browser session cookie is accepted too and takes precedence over a Bearer token.

Anonymous create still returns a delete_token in the response — that token is how an unauthenticated caller later deletes, versions, or rolls back the item. Store it; it is shown once.

Set an optional X-Shippie-Source header (api, mcp, cli, or web) to tag where the item came from. It defaults to api.

POST /api/drops — create

Create a shipped item and get a live link back. Accepts either multipart/form-data (best for real files) or application/json (best for inline content). Privacy defaults to shareable; pass privacy=sealed for an encrypted item (a sealed item must be a single HTML or SVG file — seal it client-side first). ttl_hours sets expiry and is clamped to the caller’s max (24h anonymous, 168h signed in).

Multipart fields: file (a single file), files (repeatable, for multiple), zip (a bundle that is safely extracted), html_content or svg_content (inline strings), plus title, privacy, ttl_hours, source.

JSON body: { "html_content": "<!doctype html>…" } or { "svg_content": "<svg…>" } or { "files": { "index.html": "…", "style.css": "…" } }, plus optional title, privacy, ttl_hours, source.

Success is 201 with: { "success": true, "id": "drp-…", "url": "https://shippie.app/d/drp-…", "status": "live", "expires_at": "ISO-8601", "delete_token": "…", "files": <count>, "total_bytes": <number> }.

  • 201 — created. Body carries id, url, delete_token, expires_at, files, total_bytes.
  • 400 — invalid_json / invalid_form / invalid_files / invalid_sealed_drop (e.g. a sealed item that is not one HTML/SVG), or a scan rejection (secrets or phishing in a shareable item) with a scan summary.
  • 413 — too_many_files or drop_too_large (over the per-item file count or byte budget).
  • 429 — rate_limited (per-hour burst or live-footprint cap). A Retry-After header is included; the body has reason and retry_after_ms.

GET /api/drops — list your shipped items

Returns the shipped items owned by the authenticated caller plus the current limits for that identity. With no auth it returns an empty list and the anonymous limits, so it doubles as a "what are my limits" probe.

Success is 200 with { "success": true, "identity": "account" | "local", "drops": [...], "limits": { "mode", "hour", "day", "max_ttl_hours" } }. Each drop carries id, title, privacy, source, state, url, entry_path, total_bytes, file_count, scan_status, expires_at, created_at, updated_at, version_count, latest_version, active_version.

DELETE /api/drops/{id} — delete

Permanently retire a shipped item. Authorize as the owner (session or Bearer token) OR present the delete token from create: send it as X-Shippie-Drop-Delete-Token: <token>, or as Authorization: DropDelete <token>.

Returns 200 { "success": true, "status": "deleted" } (already-deleted items return 204). Deleting frees a live-footprint slot immediately. To cut off a recipient of a sealed link, delete and ship a fresh item — the old link cannot be re-pointed.

  • 200 — deleted now.
  • 204 — was already deleted.
  • 403 — not the owner and no valid delete token.
  • 404 — no such item.

POST /api/drops/{id}/versions — publish a new version

Publish new content at the same link. Same request shapes and auth as create (owner session/Bearer, or the delete token via X-Shippie-Drop-Delete-Token / Authorization: DropDelete). The link stays the same; the new version becomes active. Previous versions are kept for rollback.

Success is 201 with { "success": true, "id", "url", "status": "live", "expires_at", "files", "total_bytes", "version": <number>, "entry_path" }.

  • 201 — new version is live.
  • 400 / 413 / 429 — same validation, size, and rate-limit rules as create.
  • 410 — drop_expired or drop_deleted (the item is gone).
  • 451 — drop_suspended (an admin kill switch has taken the item down).

GET / PATCH /api/drops/{id}/versions — history and rollback

GET lists every version (id, version_number, url, entry_path, total_bytes, file_count, created_at, active) for an owned item. Same auth as the other write paths.

PATCH rolls back to an earlier version: send JSON { "version_number": <n> }. The chosen version becomes active again at the same link. Success returns { "success": true, "id", "url", "status": "live", "expires_at", "files", "total_bytes", "version", "entry_path" }.

POST /api/drops/{id}/report — report abuse

Anyone can report a public shipped item, no auth required. Send JSON or form data with reason (one of phishing, malware, illegal, spam, other) and an optional detail string (up to 2000 chars).

Returns 201 { "success": true } when the report is filed. 400 invalid_reason for a missing or unknown reason, 404 drop_not_found if the item does not exist, and 429 rate_limited after 5 reports from the same client in an hour. Reports route to Shippie review; for takedown or copyright, also email hello@shippie.app.

Curl examples

Create a shareable page from inline HTML, anonymously: curl -X POST https://shippie.app/api/drops -H "content-type: application/json" -d '{"html_content":"<!doctype html><h1>hi</h1>","title":"hello"}'

Ship a real file with an API token (owned, longer expiry): curl -X POST https://shippie.app/api/drops -H "authorization: Bearer $SHIPPIE_TOKEN" -F "file=@poster.png" -F "ttl_hours=168"

Publish a new version of an existing item using the delete token: curl -X POST https://shippie.app/api/drops/drp-abc123def456/versions -H "x-shippie-drop-delete-token: $DELETE_TOKEN" -F "file=@poster-v2.png"

Delete a shipped item with the delete token from create: curl -X DELETE https://shippie.app/api/drops/drp-abc123def456 -H "x-shippie-drop-delete-token: $DELETE_TOKEN"

Report a shipped item for phishing: curl -X POST https://shippie.app/api/drops/drp-abc123def456/report -H "content-type: application/json" -d '{"reason":"phishing","detail":"fake login page"}'