Change Application Subdomain

PATCH

apps

{id}

network

subdomain

Change Application Subdomain

curl --request PATCH \
  --url https://api.vertracloud.app/v1/apps/{id}/network/subdomain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subdomain": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({subdomain: '<string>'})
};

fetch('https://api.vertracloud.app/v1/apps/{id}/network/subdomain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/network/subdomain"

payload = { "subdomain": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/apps/{id}/network/subdomain"

	payload := strings.NewReader("{\n  \"subdomain\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "subdomain": "myapp.vertraweb.app"
  }
}

string

required

The application ID.

string

If the application belongs to a workspace, the workspace’s ID. Required for workspace members acting on an application they don’t own.

string

required

The new subdomain, without the .vertraweb.app suffix (e.g., myapp). Between 3 and 50 characters, matching ^[a-z0-9][a-z0-9-]*[a-z0-9]$ — lowercase letters, digits and hyphens, never starting or ending with a hyphen.

Response

object

Show Toggle object

string

The full subdomain now serving the application, including the suffix.

{
  "response": {
    "subdomain": "myapp.vertraweb.app"
  }
}

This route only renames an existing subdomain. An application that was created without web publishing answers APP_HAS_NO_SUBDOMAIN — turn publishing on first with Publish Application on the Web.

The previous subdomain is released the moment the change goes through. It is not reserved for you, and anyone can take it afterwards.

Error Responses

string

The error code indicating the reason for the failure. Possible values:

VALIDATION_ERROR: The path parameter or the body failed validation (400). The response also carries message and path.
AUTH_TOKEN_MISSING, API_KEY_INVALID, SESSION_REVOKED: The Authorization header is missing, the API key is invalid, or the dashboard session was revoked (401).
API_KEY_IP_DENIED, API_KEY_SCOPE_DENIED: The API key is used from an IP outside its allowlist, or it lacks the scope the route requires (403).
USER_NOT_FOUND: The authenticated user could not be resolved (401).
ACCESS_DENIED: The user does not have permission to act on the application (403).
PLAN_DOES_NOT_SUPPORT_CUSTOM_SUBDOMAIN: The owner’s plan does not allow choosing the subdomain name (403).
APP_NOT_FOUND: The specified application does not exist (404).
APP_HAS_NO_SUBDOMAIN: The application is not published on the web, so there is nothing to rename (400).
INVALID_SUBDOMAIN_FORMAT: The value is not a valid subdomain after normalisation (400).
SUBDOMAIN_FORBIDDEN: The requested subdomain is on the platform’s reserved list (400).
SUBDOMAIN_TAKEN: Another application already uses that subdomain (409).
SUBDOMAIN_CHANGE_RATE_LIMITED: The subdomain of this application was changed less than 5 minutes ago (429).
INTERNAL_SERVER_ERROR: Unexpected failure (500).

string

A descriptive message providing additional details about the error.

{
  "code": "APP_HAS_NO_SUBDOMAIN"
}

{
  "code": "SUBDOMAIN_TAKEN"
}

{
  "code": "SUBDOMAIN_CHANGE_RATE_LIMITED"
}

This route has its own budget of 5 requests per minute, on top of the 5-minute cooldown between changes to an application’s public address. That cooldown is shared with Publish: publishing an application also starts it, and unpublishing then republishing under a new name does not get around it. See Rate Limiting.

Last modified on October 26, 2026

Change Application Subdomain

curl --request PATCH \
  --url https://api.vertracloud.app/v1/apps/{id}/network/subdomain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subdomain": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({subdomain: '<string>'})
};

fetch('https://api.vertracloud.app/v1/apps/{id}/network/subdomain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/network/subdomain"

payload = { "subdomain": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/apps/{id}/network/subdomain"

	payload := strings.NewReader("{\n  \"subdomain\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "subdomain": "myapp.vertraweb.app"
  }
}

Overview

Endpoints

Change Application Subdomain

Response

Error Responses

​Response

​Error Responses

Response

Error Responses