---
title: "Serve a sandbox's port or an App at your own hostname, with automatic HTTPS."
method: POST
path: "/v1/domains"
tags: ["domains"]
---

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

`POST /v1/domains`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `hostname` string, required
  - `sandboxId` string: The sandbox to serve, with port.
  - `port` integer: The port your server listens on inside the sandbox.
  - `appId` string: The App or Function to serve, instead of a sandbox.

## Response `200`

Success

- object
  - `id` string
  - `hostname` string
  - `sandboxId` string, nullable: The sandbox it serves; null for an App's.
  - `appId` string, nullable: The App it serves; null for a sandbox's port.
  - `port` integer
  - `state` string: pending (prove it with the TXT record), active, or released.
  - `url` string
  - `disabled` boolean: Turned off by Runtime after a report. Contact support.
  - `records` object[]
    - `type` string
    - `name` string
    - `value` string
    - `purpose` string
  - `verifiedAt` string, date-time, nullable
  - `checkedAt` string, date-time, nullable
  - `checkError` string, nullable
  - `certificate` object, nullable: An App's domain's certificate, issued before visitors arrive: point the name at the App once ready is true. Null for a sandbox's.
    - `ready` boolean
    - `expiresAt` string, date-time, nullable
    - `issuers` string[]
  - `createdAt` string, date-time
  - `pointed` boolean, nullable: The name resolves to Runtime's edge now.
  - `hint` string

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)