API

Last updated August 21, 2026

Needs the Growth plan or higher — create a key from your dashboard. Send it as an x-api-key header on every request. This is a small, deliberately minimal surface — 6 endpoints, matching the web app’s own paste → link → status → delete flow, plus listing your own sites. Every project counts against your plan’s project limit just like a site deployed from the paste form. Prefer talking to an AI assistant instead of curl? See the MCP server docs.

POST/api/v1/deploys

Deploy pasted HTML or a single-file React/Vite component.

curl https://beamship.app/api/v1/deploys \
  -H "x-api-key: YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"code": "<html><body>hi</body></html>"}'

# optional: pick your own subdomain instead of a random one
# -d '{"code": "...", "desiredSlug": "my-project"}'

HTML responds immediately with status: "ready". React/Vite components build in the background — poll the job below.

POST/api/v1/deploys/upload

Deploy an uploaded file (image, PDF, or a zip of a static site).

curl https://beamship.app/api/v1/deploys/upload \
  -H "x-api-key: YOUR_KEY" \
  -F "file=@./site.zip"

GET/api/v1/deploys/{jobId}

Check a deploy job's status.

curl https://beamship.app/api/v1/deploys/JOB_ID \
  -H "x-api-key: YOUR_KEY"

GET/api/v1/sites/{id}

Fetch a site's current status.

curl https://beamship.app/api/v1/sites/SITE_ID \
  -H "x-api-key: YOUR_KEY"

GET/api/v1/sites

List every site under this account.

curl https://beamship.app/api/v1/sites \
  -H "x-api-key: YOUR_KEY"

DELETE/api/v1/sites/{id}

Delete a site permanently.

curl -X DELETE https://beamship.app/api/v1/sites/SITE_ID \
  -H "x-api-key: YOUR_KEY"

Webhooks

Needs the Growth plan or higher — add an endpoint and pick events from your dashboard. Every delivery is a POST with a JSON body { type, data, timestamp } and an x-beamship-signature header — HMAC-SHA256 of the raw body using your endpoint’s own signing secret (base64url-encoded). There’s no retry queue in v1: a delivery that fails or times out (10s) isn’t redelivered.

site.deployed        site.expiring_soon   site.deleted
payment.succeeded    subscription.updated

Everything else the web app itself calls (billing, analytics, custom domains, and so on) is internal — not part of this API, and not guaranteed to stay stable across changes.