Atualizar Domínio do Projeto

Altera o subdomain do projeto na plataforma Zenifra.

Esta operação só se aplica a projetos HTTP com exposure: "public". Projetos privados não possuem domínio público; altere a exposição do projeto para pública antes de configurar subdomain ou domínios personalizados.

Permissões necessárias

O scope mínimo para alterar subdomain ou domínios personalizados é project.domain.update em project:<project-id>. A sessão owner tem acesso completo; assistant, member e API Keys da organização precisam desse grant.

PATCH /v1/project/:id/domain

Limite de requisições: 10 por minuto (contado por IP de origem).

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	string	ID do projeto

Headers

Header	Obrigatório	Descrição
`x-api-key` ou `Authorization`	Sim	API Key da organização ou token de usuário
`x-organization-id`	Com token de usuário	Organização ativa do projeto. Dispensável com API Key da organização
`Content-Type: application/json`	Sim	Necessário por haver body JSON

Body

Campo	Tipo	Obrigatório	Descrição
`domain`	string	Sim	Novo subdomain (de 3 a 54 caracteres, letras minúsculas, números e hífens internos)

Exemplo

{
  "domain": "meu-subdomain"
}

Resposta

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

Erros

Status	Quando ocorre
`400`	`domain` ausente ou inválido (tamanho, caracteres, hífen no início/fim ou nome reservado)
`403`	O plano do projeto não permite subdomain personalizado
`404`	Projeto não encontrado
`409`	O projeto é privado (`project is not publicly exposed`) ou o subdomain solicitado já está em uso (`DOMAIN_UNAVAILABLE`)
`409`	`PROJECT_STATE_CONFLICT`: o projeto não está em `running`, `stopped` ou `failing`, ou ainda não tem rota pública (por exemplo, um projeto Git antes do primeiro build)
`409`	`PROJECT_OPERATION_IN_PROGRESS`: outra operação de domínio, exposição ou ciclo de vida está em andamento no projeto; aguarde e tente novamente
`422`	`PROJECT_OPERATION_NOT_SUPPORTED`: o projeto não é uma aplicação HTTP
`500`	Falha ao aplicar a troca; o endereço anterior é mantido e você pode tentar novamente

Enviar o subdomain que o projeto já usa responde 200 sem alterar nada.

Domínios personalizados

Define a lista de domínios personalizados do projeto.

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

Aceita sessão de usuário ou API Key da organização e exige project.domain.update em project:<project-id>. Limite de requisições: 10 por minuto (contado por IP de origem).

Body

Campo	Tipo	Obrigatório	Descrição
`custom_domains`	array de strings	Sim	Lista completa de domínios do projeto (máximo 20). Domínios que não estiverem na lista são removidos

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

Cada chamada pode adicionar no máximo um domínio novo (only one custom domain can be added at a time). Domínios da própria Zenifra são rejeitados.

Resposta

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

custom_domain_setup traz, para cada domínio adicionado, o status da configuração, o status do certificado e os registros DNS que você precisa criar no seu provedor de DNS.

Erros

Status	Quando ocorre
`400`	Corpo inválido, domínio reservado, ou mais de um domínio novo na mesma chamada
`404`	Projeto não encontrado
`409`	O projeto é privado (`project is not publicly exposed`), ou o domínio já está em uso por outro projeto (`DOMAIN_UNAVAILABLE`)
`409`	`PROJECT_STATE_CONFLICT`: a aplicação ainda não tem rota pública (por exemplo, um projeto Git antes do primeiro build)
`409`	`PROJECT_OPERATION_IN_PROGRESS`: outra operação de domínio, exposição ou ciclo de vida está em andamento no projeto
`422`	`PROJECT_OPERATION_NOT_SUPPORTED`: o projeto não é uma aplicação HTTP

Exemplos

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

Python

import requests

API_KEY = "sua-api-key"
ORGANIZATION_ID = "sua-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": "meu-subdomain"}
)
print(response.json())

Regras do Domínio

Mínimo de 3 caracteres
Máximo de 54 caracteres
Apenas letras minúsculas, números e hífens internos
Não pode começar ou terminar com hífen
Nomes reservados da plataforma são recusados com 400, como admin, ai, api, app, auth, clients, console, docs, mail, managed, mcp, status e www; a nomeação automática também os pula
O subdomain solicitado é reservado exatamente como informado; se já estiver em uso, a API retorna 409 e não o renomeia silenciosamente
O domínio padrão resultante da Zenifra usa a zona clients.zenifra.com
Projetos HTTP privados (exposure: "private") não recebem subdomain nem aceitam atualização de domínio público

Nessa página