Surge API

The Surge API is the HTTP interface that both the CLI and the SDK are built on. Anything the CLI can do—publish, roll back, manage DNS, read analytics—happens through these endpoints, so anything the CLI can do, your own tools can do too.

If you're working in JavaScript, use the SDK rather than calling these endpoints directly; it handles authentication, upload streaming, and response parsing for you. This section documents the raw HTTP surface for everyone else.

Base URL

https://surge.surge.sh

There is no path-based versioning. Clients identify themselves with a version header carrying their own release number.

Conventions

Authentication is HTTP Basic on every authenticated endpoint. Normally the username is the literal string token and the password is your API token—see Authentication.

Responses are JSON. Errors share a common shape:

{
  "messages": ["domain must be valid."],
  "details": { "domain": "must be valid." }
}

Domains are resource paths. A project is addressed by its domain: DELETE /example.surge.sh tears down that project, GET /example.surge.sh/list lists its revisions.

Long-running operations stream. The deploy, certificate, and custom-SSL endpoints respond with newline-delimited JSON (Accept: application/x-ndjson): one JSON object per line, emitted as the work progresses. A line with "type": "info" signals success. See Deploys.

Common status codes

Code Meaning
200 / 201 / 202 Success.
401 Missing or invalid credentials. The reason response header explains why.
403 Authenticated, but not allowed—no permission for the domain, rate limited, or project too large.
404 No such project, revision, or account.
405 Operation not available for this domain (e.g. DNS management on a non-apex domain).
409 Conflict—for example, deleting an account that still has projects.
422 Invalid domain.

A quick tour

# Mint a token with your email and password
curl -X POST https://surge.surge.sh/token -u you@example.com:password

# List your projects
curl https://surge.surge.sh/list -u token:YOUR_TOKEN

# Deploy a tarball
tar czf - -C ./my-site . | curl -X PUT https://surge.surge.sh/my-site.surge.sh \
  -u token:YOUR_TOKEN \
  -H "Content-Type: application/gzip" \
  -H "Accept: application/x-ndjson" \
  --data-binary @-

# Take it down
curl -X DELETE https://surge.surge.sh/my-site.surge.sh -u token:YOUR_TOKEN

In this section