Endpoint Reference

All endpoints are relative to https://surge.surge.sh and require token authentication unless noted. Errors use the shared { messages, details } shape described in the overview.

Projects

Method & path Description
PUT /:domain Deploy a gzipped tarball to the domain. Streaming—see Deploys.
DELETE /:domain Tear the project down. 200 { "msg": "project removed" }.
GET /list All projects on the account. Array of { domain, rev, timeAgoInWords, planName, … }.
GET /:domain/metadata.json Metadata for the live revision: revision id, deploy message, publisher email, file counts, sizes, and the project's active config. GET /:domain/:rev/metadata.json targets a specific revision.
GET /:domain/manifest.json The file manifest—a map of path to { size, md5 }. Also available per revision.
DELETE /:domain/cache Purge the project from every edge node's cache. 200 { "confirmed": [...], "unconfirmed": [...] }.

Revisions

Revision ids are millisecond timestamps (e.g. 1719852000000). Every revision keeps a permanent preview URL.

Method & path Description
GET /:domain/list All revisions of the project: { rev, friendlySize, timeAgoInWords, publicFileCount, … }. 404 if none.
POST /:domain/rollback Point the domain at the previous revision. 200 { revision, former, instances }.
POST /:domain/rollfore Point the domain at the next revision.
PUT /:domain/rev Cut over to the latest revision; PUT /:domain/rev/:rev to a specific one.
DELETE /:domain/rev/:rev Discard a revision from the system.

Certificates

Method & path Description
GET /:domain/certs Certificate information for the domain.
PUT /:domain/encrypt Provision a managed certificate. Streaming NDJSON—see Deploys.
PUT /:domain/ssl Upload a custom PEM bundle. Content-Type: application/x-pem-file. Paid plans only.

DNS

DNS endpoints apply to apex domains delegated to Surge's name servers; on other domains they respond 405. Records take the form { type, name, value, priority }.

Method & path Description
GET /:domain/dns The custom records you've added.
POST /:domain/dns Add a record. 400 on validation failure.
DELETE /:domain/dns/:id Remove a record.
GET /:domain/zone The full zone, including the records Surge manages automatically.
POST /:domain/zone Add a zone record.
DELETE /:domain/zone/:id Remove a zone record.

Collaborators

Method & path Description
POST /:domain/collaborators Invite collaborators. Body { "emails": ["a@example.com"] }. 202 { "invites": [{ email, status }] }.
DELETE /:domain/collaborators Revoke collaborators. Body { "emails": [...] }. 202 { "successes": [...], "fails": [...] }.

Settings & analytics

Method & path Description
PUT /:domain/settings Update project settings. Body is a map of setting → value; the response echoes the resulting configuration.
GET /:domain/analytics Aggregated traffic analytics for the past 14 days: visits, uniques, connections, bandwidth, status codes, encryption breakdown, sources, and per-file load. Cached for 15 minutes.
GET /:domain/usage Bandwidth usage—same data source as analytics.
GET /:domain/audit The project's state on every edge node, including a live TLS certificate check per node.

Account, tokens & billing

Method & path Description
POST /token Mint an API token (email + password auth). 201 { email, token }.
POST /token/reset/:email Send password reset instructions. No auth. Always 201.
POST /verification Send an email verification link.
GET /account The account object, with plan and card.
DELETE /account Permanently delete the account. 409 while projects still exist.
GET /plans Available plans, the current plan, and card status. GET /:domain/plans scopes to a project.
PUT /plan Subscribe to or change a plan. Body { plan, token, timestamp }.
PUT /card Update the payment card. Body { token } (a Stripe source token). 201 on success.
POST /upgrade/link Mint a browser checkout URL, valid 48 hours. 201 { url }.
POST /billing/link Mint a browser billing portal URL (card, invoices, cancellation), valid 48 hours. 201 { url }.

Platform stats

Method & path Description
GET /stats Public, unauthenticated platform statistics—deploy counts, bytes published, project totals. CORS-enabled.