---
title: "Create"
method: POST
path: "/reserved_domains"
tags: ["ReservedDomains"]
---

# Create

`POST /reserved_domains`

Create a new reserved domain.

## Headers

- `ngrok-version` integer, required

## Request body

- ReservedDomainCreate
  - `domain` string — hostname of the reserved domain
  - `region` string — deprecated: With the launch of the ngrok Global Network domains traffic is now handled globally. This field applied only to endpoints. Note that agents may still connect to specific regions. Optional, null by default. (au, eu, ap, us, jp, in, sa)
  - `description` string — human-readable description of what this reserved domain will be used for
  - `metadata` string — arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
  - `certificate_id` string — ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
  - `certificate_management_policy` ReservedDomainCertPolicy
    - `authority` string — certificate authority to request certificates from. The only supported value is letsencrypt.
    - `private_key_type` string — type of private key to use when requesting certificates. Defaults to ecdsa, can be either rsa or ecdsa.
  - `resolves_to` ReservedDomainResolvesToEntry[] — DNS resolver targets configured for the reserved domain, or empty for "global" resolution.
    - `value` string — accepts an ngrok point-of-presence shortcode, or "global"

## Response `201`

Create a new reserved domain.

- ReservedDomain
  - `id` string — unique reserved domain resource identifier
  - `uri` string — URI of the reserved domain API resource
  - `created_at` string — timestamp when the reserved domain was created, RFC 3339 format
  - `description` string — human-readable description of what this reserved domain will be used for
  - `metadata` string — arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
  - `domain` string — hostname of the reserved domain
  - `region` string — deprecated: With the launch of the ngrok Global Network domains traffic is now handled globally. This field applied only to endpoints. Note that agents may still connect to specific regions. Optional, null by default. (au, eu, ap, us, jp, in, sa)
  - `cname_target` string — DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)
  - `certificate` Ref
    - `id` string — a resource identifier
    - `uri` string — a uri for locating a resource
  - `certificate_management_policy` ReservedDomainCertPolicy
    - `authority` string — certificate authority to request certificates from. The only supported value is letsencrypt.
    - `private_key_type` string — type of private key to use when requesting certificates. Defaults to ecdsa, can be either rsa or ecdsa.
  - `certificate_management_status` ReservedDomainCertStatus
    - `renews_at` string — timestamp when the next renewal will be requested, RFC 3339 format
    - `provisioning_job` ReservedDomainCertJob
      - `error_code` string — if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
      - `msg` string — a message describing the current status or error
      - `started_at` string — timestamp when the provisioning job started, RFC 3339 format
      - `retries_at` string — timestamp when the provisioning job will be retried
  - `acme_challenge_cname_target` string — DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.
  - `resolves_to` ReservedDomainResolvesToEntry[] — DNS resolver targets configured for the reserved domain, or empty for "global" resolution.
    - `value` string — accepts an ngrok point-of-presence shortcode, or "global"

---

[API](https://skmtc.net/ngrok/apis/ngrok-openapi.md) · [All operations](https://skmtc.net/ngrok/apis/ngrok-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ngrok/ngrok-openapi/versions/1994bbb04714/schema)