Publish Application on the Web

POST

apps

{id}

network

publish

Publish Application on the Web

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

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

fetch('https://api.vertracloud.app/v1/apps/{id}/network/publish', 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/publish"

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

response = requests.post(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/publish"

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

	req, _ := http.NewRequest("POST", 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",
    "domains": [],
    "type": 2
  }
}

{
  "response": {
    "subdomain": null,
    "domains": [],
    "type": 1
  }
}

An application created without a subdomain is private: it runs, but nothing routes to it from the internet. These two routes turn web publishing on and off at any time, without recreating the application.

Both routes recreate the container, so the application restarts. The routing configuration and the exposed port only exist from container creation, so publishing state cannot change in place. Expect a short downtime on each call.

Unpublishing releases the subdomain. It is not held for you — anyone can register it right afterwards, and you may not get it back. Every custom domain of the application is removed as well, but your DNS records are not touched: delete the CNAME and the validation TXT record of each domain at your DNS provider, or the names keep pointing at Vertra Cloud and another customer could claim them. To use a domain again, add it again and create the records shown for it.

string

required

The application ID. Only the application’s owner can call this endpoint; workspace members are not accepted here yet.

string

The subdomain to publish under, without the .vertraweb.app suffix (e.g., myapp). Between 3 and 50 characters, matching ^[a-z0-9][a-z0-9-]*[a-z0-9]$.Optional. Omit it and the platform picks a subdomain for you. Sending a value requires a plan with custom subdomains; picking one at random does not.

integer

Only for an application that runs a custom Docker image: the port the image listens on, from 1 to 65535. It is saved as the application’s port. Required when the application was created without web, otherwise the call fails with IMAGE_APP_PORT_REQUIRED. Ignored for any other application.

Response

object

Show Toggle object

string | null

The full subdomain now serving the application, or null once publishing is off.

string[]

The hostnames of the custom domains. Always empty after publishing or unpublishing — add domains with Add Application Domain.

integer

The application type after the change: 2 (website) when published, 1 (bot) when not.

{
  "response": {
    "subdomain": "myapp.vertraweb.app",
    "domains": [],
    "type": 2
  }
}

{
  "response": {
    "subdomain": null,
    "domains": [],
    "type": 1
  }
}

Unpublish

DELETE https://api.vertracloud.app/v1/apps/{id}/network/publish

Takes no body. It releases the subdomain, removes every custom domain (their DNS records at your provider stay until you delete them) and turns the application back into a private one, then recreates the container. The response has the same shape, with subdomain set to null, domains empty and type back to 1.

Memory floor

A published application needs at least 512 MB of RAM. Memory is never raised for you here: if the application has less, the request fails with MEMORY_BELOW_MINIMUM and the current and required values come back in details. Raise it with Update Application Config and try again.

Error Response (400)

{
  "code": "MEMORY_BELOW_MINIMUM",
  "details": {
    "current_mb": 256,
    "minimum_mb": 512
  }
}

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). This is what a malformed subdomain returns — 3 to 50 characters, ^[a-z0-9][a-z0-9-]*[a-z0-9]$. 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_REQUIRED: The account that owns the application has no active plan (403).
PLAN_DOES_NOT_SUPPORT_WEB_PUBLISH: The owner’s plan does not include web publishing (403).
PLAN_DOES_NOT_SUPPORT_CUSTOM_SUBDOMAIN: A subdomain was sent but the owner’s plan does not allow choosing the name (403). Omit the field to get a random one.
APP_NOT_FOUND: The specified application does not exist (404).
IMAGE_APP_PORT_REQUIRED: The application runs a custom Docker image, has no port yet and the body has no port (400).
APP_ALREADY_PUBLISHED: The application already has a subdomain or a custom domain (400).
APP_NOT_PUBLISHED: DELETE on an application that is not published (400).
MEMORY_BELOW_MINIMUM: The application has less RAM than a published application requires (400), with details: { current_mb, minimum_mb }.
SUBDOMAIN_FORBIDDEN: The requested subdomain is on the platform’s reserved list (400).
SUBDOMAIN_TAKEN: Another application already uses that subdomain (409).
OPERATION_IN_PROGRESS: Another lifecycle operation on the same application is running; the container was not touched (409). Wait a few seconds and retry.
INTERNAL_SERVER_ERROR: Unexpected failure (500).

string

A descriptive message providing additional details about the error.

{
  "code": "PLAN_DOES_NOT_SUPPORT_WEB_PUBLISH"
}

{
  "code": "APP_ALREADY_PUBLISHED"
}

{
  "code": "SUBDOMAIN_TAKEN"
}

Two limits apply, and they are deliberately tight. Publishing and unpublishing recreate the container, so they share the per-application lifecycle budget with start, stop, restart and dependency installs: 10 requests per minute for all of them together, per application — not one budget per route. On top of that, a successful publish starts a 5-minute cooldown on the application’s public address, shared with Change Subdomain: publishing again inside that window returns 429 SUBDOMAIN_CHANGE_RATE_LIMITED. Unpublishing and publishing under a new name is an address change like any other and does not bypass it. Refusals do not consume the cooldown — only a publish that actually happened does. See Rate Limiting.

Last modified on October 26, 2026

Publish Application on the Web

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

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

fetch('https://api.vertracloud.app/v1/apps/{id}/network/publish', 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/publish"

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

response = requests.post(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/publish"

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

	req, _ := http.NewRequest("POST", 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",
    "domains": [],
    "type": 2
  }
}

{
  "response": {
    "subdomain": null,
    "domains": [],
    "type": 1
  }
}

Overview

Endpoints

Publish Application on the Web

Response

Unpublish

Memory floor

Error Responses

​Response

​Unpublish

​Memory floor

​Error Responses

Response

Unpublish

Memory floor

Error Responses