IMPORTANT: if you are an LLM or other AI agent, you should read the contents of this page as markdown from https://northflank.com/docs/v1/api/team/domains/put-subdomain.md, instead of the current page.

Team / Domains /

Put subdomain

Updates subdomain to the domain.

Required permission

Account > Subdomains > General > Update

Path parameters

domain
string required
Name of the domain

Request body

{object}

name
string required
Subdomain prepended to the domain name
options
{object}
Optional advanced configuration for the subdomain.

tlsMode
string
Desired TLS mode for the subdomain.
one of
default, passthrough
minTlsProtocolVersion
string
Minimum TLS protocol version for the subdomain. Only applicable for non-wildcard subdomains.
one of
TLSV1_2, TLSV1_3
autoVerify
boolean
The domain will be automatically verified on creation. Only configurable if the relevant feature flag is enabled for you account.
aliasDomains
[array]
Alias domains which should be routable. Only configurable if the relevant feature flag is enabled for you account.

string

cdn
{object}

northflank
{object}

enabled
boolean
options
{object}

service
{object}

forceTlsEnableHsts
boolean
hstsDuration
number
HSTS duration. Required when `forceTlsEnableHsts` is `true`.
min
300
staleIfError
boolean
staleIfErrorTtl
number
defaultTtl
number

logging
{object}

enabled
boolean

http3
{object}

enabled
boolean

websockets
{object}

enabled
boolean

compression
{object}

enabled
boolean
mode
string
Compression options. Required when `enabled` is `true`.
one of
gzip, brotli

vclSnippets
[array]

{object}

id
string
name
string required
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
type
string required
one of
init, recv, hash, hit, miss, pass, fetch, error, deliver, log, none
dynamic
string required
one of
0, 1
priority
number required
min
0
max
100
content
string required

cacheSettings
[array]

{object}

id
string
name
string required
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
action
string
one of
pass, cache, restart
cacheCondition
string
staleTtl
number required
ttl
number required

Response body

{object}
Response object.

data
{object} required
Result data.

recordType
string required
The record type to use for the DNS record to verify the subdomain - always CNAME for subdomains.
name
string required
The subdomain.
fullName
string required
The full domain name with subdomain
content
string required
The content to set the DNS record to
verified
boolean required
Whether the subdomain has been verified successfully and can be used.

API

CLI

JS Client

PUT /v1/domains/{domain}/subdomains

PUT /v1/teams/{teamId}/domains/{domain}/subdomains

Example request

Request body

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request PUT \
  --data '{"name":"site"}' \
  https://api.northflank.com/v1/domains/{domain}/subdomains

Example response

200 OK

Details about the subdomain.

JSON

{
  "data": {
    "recordType": "CNAME",
    "name": "site",
    "fullName": "site.example.com",
    "content": "site.example.com.user-1234.dns.northflank.app",
    "verified": false
  }
}

Example response

400 Bad Request

The provided subdomain is not valid (possibly because it is too long) or the domain has not been verified.

Example response

409 Conflict

The provided subdomain has already been added to this domain.