Update Project Domain

Changes the project subdomain on the Zenifra platform.

This operation applies only to HTTP projects with exposure: "public". Private projects do not have a public domain; change the project exposure to public before configuring a subdomain or custom domains.

Required permissions

The minimum scope to change a subdomain or custom domains is project.domain.update on project:<project-id>. An owner session has full access; assistant, member, and organization API Keys need this grant.

PATCH /v1/project/:id/domain

Rate limit: 10 requests per minute (counted per source IP).

Path Parameters

Parameter	Type	Description
`id`	string	Project ID

Headers

Header	Required	Description
`x-api-key` or `Authorization`	Yes	Organization API Key or user token
`x-organization-id`	With a user token	Active project organization. Not needed with an organization API key
`Content-Type: application/json`	Yes	Required because the request has a JSON body

Body

Field	Type	Required	Description
`domain`	string	Yes	New subdomain (3–54 characters, lowercase letters, numbers, and internal hyphens)

Example

{
  "domain": "my-subdomain"
}

Response

{
  "status": "success",
  "message": "updated with success"
}

Errors

Status	When it happens
`400`	Missing or invalid `domain` (length, characters, or hyphen at the start/end)
`403`	The project plan does not allow a custom subdomain
`404`	Project not found
`409`	The project is private, or the requested subdomain is not available
`503`	The address could not be assigned right now; try again shortly

Custom domains

Sets the project's list of custom domains.

PATCH /v1/project/:id/custom-domains

Accepts a user session or an organization API Key and requires project.domain.update on project:<project-id>. Rate limit: 10 requests per minute (counted per source IP).

Body

Field	Type	Required	Description
`custom_domains`	array of strings	Yes	Complete list of the project's domains (maximum 20). Domains not in the list are removed

{
  "custom_domains": ["www.example.com"]
}

Each call can add at most one new domain. Reserved platform names are rejected.

Response

{
  "status": "success",
  "message": "custom domains updated with success",
  "custom_domains": ["www.example.com"],
  "custom_domain_setup": [
    {
      "hostname": "www.example.com",
      "status": "pending",
      "ssl_status": "pending_validation",
      "dns_records": []
    }
  ]
}

custom_domain_setup lists, for each added domain, the setup status, the certificate status, and the DNS records you need to create at your DNS provider.

Errors

Status	When it happens
`400`	Invalid body, reserved domain, or more than one new domain in the same call
`404`	Project not found
`409`	The project is private (`project is not publicly exposed`), or the domain is not available

Examples

curl -X PATCH "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/domain" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{"domain": "my-subdomain"}'

Python

import requests

API_KEY = "your-api-key"
ORGANIZATION_ID = "your-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

response = requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/domain",
    headers={"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID},
    json={"domain": "my-subdomain"}
)
print(response.json())

Domain Rules

Minimum of 3 characters
Maximum of 54 characters
Lowercase letters, numbers, and internal hyphens only
Cannot start or end with hyphen
The requested subdomain is reserved exactly as provided; if it is already in use, the API returns 409 instead of silently renaming it
The resulting Zenifra default domain uses the clients.zenifra.com zone
Private HTTP projects (exposure: "private") do not receive a subdomain and cannot update a public domain

On this page