---
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[] — Region and IP resolution targets configured for the Domain.
    - `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[] — Region and IP resolution targets configured for the Domain.
    - `value` string — accepts an ngrok point-of-presence shortcode, or "global"

## Other responses

- `4XX` — An error. The body carries a machine-readable error_code and a human-readable msg; every code is documented at https://ngrok.com/docs/errors. A 429 with error code ERR_NGROK_226 means the account exceeded the documented request-rate limit.
- `5XX` — An error. The body carries a machine-readable error_code and a human-readable msg; every code is documented at https://ngrok.com/docs/errors. A 429 with error code ERR_NGROK_226 means the account exceeded the documented request-rate limit.

## Changes

- **2026-01-23** `1994bbb04714` — 2 info
  - added the new optional request property `resolves_to`
  - added the optional property `resolves_to` to the response with the `201` status

[Change history](https://skmtc.dev/ngrok/apis/ngrok-openapi/changes/reserved_domains/post.md)

---

[API](https://skmtc.dev/ngrok/apis/ngrok-openapi.md) · [All operations](https://skmtc.dev/ngrok/apis/ngrok-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ngrok/ngrok-openapi/revisions/c697539ac350/schema)