domains

Serve a sandbox's port or an App at your own hostname, with automatic HTTPS.

Claims the hostname and answers the DNS records to set: a TXT record that proves the name is yours, and a CNAME (an A record for an apex name) that sends visitors here. Checks the TXT record at once. Needs a kept top-up. Calling it again with another sandbox or port points the name there. With appId instead of sandboxId and port, an App serves the name through every deploy and rollback; add its _acme-challenge CNAME too, and point the name at the App once certificate.ready is true.

post/v1/domains

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/domains
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

hostnamestring required
sandboxIdstring

The sandbox to serve, with port.

portinteger

The port your server listens on inside the sandbox.

appIdstring

The App or Function to serve, instead of a sandbox.

Response

Success

idstring
hostnamestring
sandboxIdstring nullable

The sandbox it serves; null for an App's.

appIdstring nullable

The App it serves; null for a sandbox's port.

portinteger
statestring

pending (prove it with the TXT record), active, or released.

urlstring
disabledboolean

Turned off by Runtime after a report. Contact support.

verifiedAtstring date-time nullable
checkedAtstring date-time nullable
checkErrorstring nullable
createdAtstring date-time
pointedboolean nullable

The name resolves to Runtime's edge now.

hintstring

Changes

No recorded changes to this operation across all 1 revision of this API.