Method Reference

Every JSON method follows Node's callback convention—the last argument is always function(err, data). Arguments marked optional may be omitted entirely; the remaining arguments shift left. creds is a credentials object as described in Client & Authentication.

The streaming methods (publish, encrypt, ssl) return an EventEmitter instead and are covered in Publishing & Streams.

Account & tokens

Method	Calls	Description
`token(creds, cb)`	`POST /token`	Exchange email + password for a token. Yields `{ user: "token", pass: "…" }`, ready to use as `creds`.
`reset(email, cb)`	`POST /token/reset/:email`	Send a password reset email. No auth required.
`account(creds, cb)`	`GET /account`	Fetch the account: email, verification state, plan, card.
`verification(creds, cb)`	`POST /verification`	Send an email verification link. Yields `{ verified: true }` if already verified, `{ sent: true }` if sent.
`nuke(creds, cb)`	`DELETE /account`	Permanently delete the account. Fails with a 409 while projects still exist.
`stats(cb)`	`GET /stats`	Public platform statistics. No auth required.

Projects & revisions

Method	Calls	Description
`list(creds, cb)`	`GET /list`	All projects on the account.
`list(domain, creds, cb)`	`GET /:domain/list`	All revisions of one project.
`teardown(domain, creds, cb)`	`DELETE /:domain`	Take the project down and remove it.
`rollback(domain, creds, cb)`	`POST /:domain/rollback`	Point the domain at the previous revision.
`rollfore(domain, creds, cb)`	`POST /:domain/rollfore`	Point the domain at the next revision.
`cutover(domain, [rev], creds, cb)`	`PUT /:domain/rev/:rev`	Promote a revision to live (latest if `rev` omitted).
`discard(domain, [rev], creds, cb)`	`DELETE /:domain/rev/:rev`	Delete a revision from the system.
`bust(domain, creds, cb)`	`DELETE /:domain/cache`	Purge the project from every edge node's cache.
`metadata(domain, [rev], creds, cb)`	`GET /:domain/metadata.json`	Deploy metadata for the live (or given) revision.
`manifest(domain, [rev], creds, cb)`	`GET /:domain/manifest.json`	File manifest—a map of path → size and checksum.

Domains, DNS & certificates

Method	Calls	Description
`certs(domain, creds, cb)`	`GET /:domain/certs`	Certificate information for the domain.
`dns(domain, creds, cb)`	`GET /:domain/dns`	List the domain's DNS records.
`dnsAdd(domain, record, creds, cb)`	`POST /:domain/dns`	Add a DNS record, e.g. `{ type: "MX", name: "@", priority: "10", value: "mail.example.com" }`.
`dnsRem(domain, id, creds, cb)`	`DELETE /:domain/dns/:id`	Remove a DNS record by id.
`zone(domain, creds, cb)`	`GET /:domain/zone`	The full zone, including records Surge manages for you.
`zoneAdd(domain, record, creds, cb)`	`POST /:domain/zone`	Add a zone record.
`zoneRem(domain, id, creds, cb)`	`DELETE /:domain/zone/:id`	Remove a zone record by id.

DNS methods only apply to apex domains you've pointed at Surge's name servers—see DNS on the platform.

Collaborators

Method	Calls	Description
`invite(domain, { emails }, creds, cb)`	`POST /:domain/collaborators`	Invite collaborators by email.
`revoke([domain, ...emails], creds, cb)`	`DELETE /:domain/collaborators`	Revoke collaborators. Takes a single array mixing the domain and the emails to remove.

Settings & analytics

Method	Calls	Description
`settings(domain, props, creds, cb)`	`PUT /:domain/settings`	Update project settings.
`analytics(domain, creds, cb)`	`GET /:domain/analytics`	Traffic analytics for the past 14 days.
`usage(domain, creds, cb)`	`GET /:domain/usage`	Bandwidth usage data.
`audit(domain, creds, cb)`	`GET /:domain/audit`	Per-edge-node state of the project, including live certificate checks.

Billing & plans

Method	Calls	Description
`plans([domain], headers, creds, cb)`	`GET /plans`	Available plans, the current plan, and card status.
`plan(args, creds, cb)`	`PUT /plan`	Subscribe to or change a plan: `{ plan, token, timestamp }`.
`card({ token }, creds, cb)`	`PUT /card`	Update the payment card with a Stripe source token.
`upgradeLink([plan], creds, cb)`	`POST /upgrade/link`	Mint a browser checkout URL (valid 48 hours).
`billingLink(creds, cb)`	`POST /billing/link`	Mint a browser billing portal URL (valid 48 hours).

Error handling

On success, callbacks receive (null, data) where data is the parsed response body. On failure, the error arrives as the first and only argument, in one of three shapes:

// An HTTP error response — the response body, with status attached
{ messages: ["domain must be valid."], details: { domain: "must be valid." }, status: 422 }

// Some endpoints use a single message
{ message: "Not Found", status: 404 }

// A network failure — the request never completed
{ errors: ["request did not complete"], details: { request: "did not complete" } }

Check err.status for the HTTP code, and fall back through err.messages, err.message, and err.errors when displaying the failure—the CLI does exactly this.