> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Adicionar domínio
> Aponte um domínio seu para um site: a resposta traz os registros para criar no DNS.
O domínio próprio está **em breve**: enquanto não for liberado para a sua conta, esta rota responde `503 custom_domains_unavailable`.
Mande só o nome (`loja.com.br`). A resposta traz o domínio `pending` e, em `records`, o **CNAME** para `domains.cubehost.dev` e o **TXT** `_cube-verify.`. Crie os dois no DNS do domínio; a Cube confere sozinha a cada minuto e, com o TXT certo, o domínio passa a abrir o site. O HTTPS sai sozinho.
Para o `www`, adicione também `www.loja.com.br` com `redirectTo: "loja.com.br"`: quem abrir o `www` vai para a raiz (ou o contrário, se a raiz for a que redireciona). Os dois usam o mesmo TXT.
## Erros comuns
| Código | HTTP | O que fazer |
| ------------------------------------------------------------------------ | ---- | --------------------------------------------------------------------------------- |
| [`custom_domains_unavailable`](/errors#param-custom-domains-unavailable) | 503 | O domínio próprio ainda não chegou à sua conta: use o endereço em `cubehost.dev`. |
| [`custom_domain_not_allowed`](/errors#param-custom-domain-not-allowed) | 403 | Mude para o Tower, Fortress ou Monolith. |
| [`invalid_domain`](/errors#param-invalid-domain) | 400 | Mande só o nome, sem `https://`, barra nem porta. |
| [`reserved_domain`](/errors#param-reserved-domain) | 422 | Use um domínio seu; para mudar o endereço em `cubehost.dev`, troque o subdomínio. |
| [`not_a_site`](/errors#param-not-a-site) | 422 | Domínio só vale para sites e APIs. |
| [`domain_taken`](/errors#param-domain-taken) | 409 | O domínio está em outro site da conta ou é de outra conta. |
| [`plan_limit_reached`](/errors#param-plan-limit-reached) | 422 | Remova um domínio que não usa ou mude de plano (`limit` diz quantos cabem). |
| [`invalid_redirect`](/errors#param-invalid-redirect) | 422 | `redirectTo` tem que ser outro domínio do site que abre o site direto. |
| [`insufficient_permission`](/errors#param-insufficient-permission) | 403 | Use uma chave de leitura e escrita. |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml POST /projects/{id}/domains
openapi: 3.1.0
info:
title: API da Cube Hosting
version: 1.0.0
description: >-
Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
inicie, pare, reinicie, leia logs e métricas, cuide das variáveis de
ambiente, faça e baixe backups, volte para uma versão anterior, crie bancos
de dados (PostgreSQL, MySQL, MongoDB e Redis), guarde arquivos privados no
Blob, use um domínio seu nos sites e veja o uso do plano. Para agentes de
IA, o servidor MCP da conta (`POST https://app.cubehosting.com.br/api/mcp`,
JSON-RPC, com a mesma chave) está em
https://docs.cubehosting.com.br/account-mcp.
contact:
name: Cube Hosting
url: https://discord.gg/pv6D9tUsDV
servers:
- url: https://app.cubehosting.com.br/api
security:
- bearerAuth: []
tags:
- name: Projetos
- name: Controle
- name: Logs e métricas
- name: Variáveis de ambiente
- name: Backups
- name: Versões dos envios
- name: Bancos de dados
- name: Blob
- name: Domínios
- name: Templates
- name: Avisos
- name: Conta
paths:
/projects/{id}/domains:
post:
tags:
- Domínios
summary: Adicionar domínio
description: >-
Adiciona um domínio seu ao site, a partir do plano Tower. Responde com o
domínio `pending` e os registros para criar no DNS dele. Com
`redirectTo` (outro domínio do mesmo site que abre o site direto), quem
abrir este vai para o outro: é o jeito de pôr o `www` levando à raiz, ou
o contrário. O `www` e a raiz usam o mesmo TXT. Só o domínio verificado
abre o site, e um domínio verificado é de uma conta só.
operationId: createDomain
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DomainInput'
examples:
raiz:
summary: A raiz
value:
hostname: loja.com.br
www:
summary: O www levando à raiz
value:
hostname: www.loja.com.br
redirectTo: loja.com.br
responses:
'201':
description: O domínio, verificando.
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
$ref: '#/components/schemas/Domain'
example:
domain:
id: 01JA9K3M5P7R9T1V3X5Z7B9D1F
projectId: 01J8Z4B2QK7M3V9T0XW5R6N8CD
hostname: loja.com.br
redirectTo: null
status: pending
error: null
records:
- type: CNAME
name: loja.com.br
value: domains.cubehost.dev
isOk: false
- type: TXT
name: _cube-verify.loja.com.br
value: cube-verify=4a4163549b3f77ae5fbfff6fa7480999
isOk: false
verifiedAt: null
checkedAt: '2026-09-28T15:21:02.114Z'
createdAt: '2026-09-28T15:09:40.000Z'
project:
id: 01J8Z4B2QK7M3V9T0XW5R6N8CD
name: Loja
'400':
description: >-
Domínio fora do formato: só o nome, sem `https://`, barra, porta nem
curinga.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_domain:
summary: invalid_domain
value:
status: error
code: invalid_domain
message: >-
Digite só o domínio, como loja.com.br ou www.loja.com.br,
sem https:// nem barra.
'401':
description: Chave ausente, inválida ou revogada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_api_key:
summary: invalid_api_key
value:
status: error
code: invalid_api_key
message: >-
Chave de API inválida ou revogada. Confira o cabeçalho
"Authorization: Bearer " ou crie outra em Chaves de
API no painel.
'403':
description: A chave é só de leitura, ou o plano não tem domínio próprio.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_permission:
summary: insufficient_permission
value:
status: error
code: insufficient_permission
message: >-
Esta chave é só de leitura. Para enviar, iniciar, parar,
reiniciar, mexer nas variáveis, fazer e baixar backups,
baixar e voltar versões dos envios, criar, ligar, desligar
e ver a senha dos bancos de dados ou enviar e apagar
arquivos do Blob, crie uma chave de leitura e escrita no
painel.
custom_domain_not_allowed:
summary: custom_domain_not_allowed
value:
status: error
code: custom_domain_not_allowed
message: >-
O plano Stack não tem domínio próprio. Ele vem no Tower,
Fortress e Monolith.
'404':
description: O projeto não existe ou não é da sua conta.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
summary: not_found
value:
status: error
code: not_found
message: Projeto não encontrado.
'409':
description: >-
O domínio já está em outro site da conta ou outra conta já provou a
posse.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
domain_taken:
summary: domain_taken
value:
status: error
code: domain_taken
message: >-
Este domínio já é de outra conta. Se ele é seu, fale com o
suporte.
'422':
description: Bot, endereço da Cube, limite do plano ou redirecionamento inválido.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_a_site:
summary: not_a_site
value:
status: error
code: not_a_site
message: >-
Só sites e APIs recebem domínio próprio. Bots não recebem
visitas pela internet.
reserved_domain:
summary: reserved_domain
value:
status: error
code: reserved_domain
message: >-
Endereços em cubehost.dev e do painel não podem ser
domínio próprio. Para mudar o endereço em cubehost.dev,
troque o subdomínio padrão.
plan_limit_reached:
summary: plan_limit_reached
value:
status: error
code: plan_limit_reached
message: >-
O plano Tower tem até 10 domínios próprios, somando todos
os sites (o www conta como um). Remova um que não usa ou
mude para um plano maior.
limit: 10
invalid_redirect:
summary: invalid_redirect
value:
status: error
code: invalid_redirect
message: >-
O redirecionamento precisa ir para outro domínio deste
site que abre o site direto (sem redirecionar de novo).
'429':
description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limit_exceeded:
summary: rate_limit_exceeded
value:
status: error
code: rate_limit_exceeded
message: >-
A sua conta passou do limite da API do plano Free: 10
pedidos por minuto. Espere 42 s e tente de novo.
too_many_attempts:
summary: too_many_attempts
value:
status: error
code: too_many_attempts
message: Muitas tentativas. Tente de novo em 15 minutos.
'503':
description: O domínio próprio ainda não está liberado para a conta (em breve).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
custom_domains_unavailable:
summary: custom_domains_unavailable
value:
status: error
code: custom_domains_unavailable
message: >-
O domínio próprio ainda não está disponível. Ele chega em
breve.
x-codeSamples:
- lang: bash
label: curl
source: >-
curl -X POST
https://app.cubehosting.com.br/api/projects/$PROJECT_ID/domains \
-H "Authorization: Bearer $CUBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hostname": "loja.com.br"}'
- lang: javascript
label: Node.js
source: >-
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const res = await
fetch(`${API}/projects/${process.env.PROJECT_ID}/domains`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ hostname: 'loja.com.br' }),
});
const { domain } = await res.json();
for (const r of domain.records) console.log(r.type, r.name,
r.value);
- lang: python
label: Python
source: |-
import os
import requests
API = "https://app.cubehosting.com.br/api"
headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}
r = requests.post(
f"{API}/projects/{os.environ['PROJECT_ID']}/domains",
headers=headers,
json={"hostname": "loja.com.br"},
timeout=30,
)
r.raise_for_status()
for rec in r.json()["domain"]["records"]:
print(rec["type"], rec["name"], rec["value"])
components:
parameters:
ProjectId:
name: id
in: path
required: true
description: >-
O ID do projeto (26 caracteres). Aparece no painel, no topo do projeto,
e em `GET /projects`.
schema:
type: string
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
example: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
schemas:
DomainInput:
type: object
required:
- hostname
additionalProperties: false
properties:
hostname:
type: string
description: >-
Só o domínio (`loja.com.br`, `www.loja.com.br`), sem `https://`,
barra nem porta.
redirectTo:
type:
- string
- 'null'
description: >-
Opcional: outro domínio do mesmo site, que abre o site direto, para
onde este redireciona.
Domain:
type: object
description: Um domínio próprio de um site.
required:
- id
- projectId
- hostname
- redirectTo
- status
- error
- records
- verifiedAt
- checkedAt
- createdAt
- project
properties:
id:
type: string
description: ID do domínio (26 caracteres).
projectId:
type: string
description: O site que o domínio abre.
hostname:
type: string
description: >-
O domínio, em minúsculas (acento em punycode: `café.com.br` →
`xn--caf-dma.com.br`).
redirectTo:
type:
- string
- 'null'
description: >-
Outro domínio do site para onde este redireciona (`308`, com o
caminho); `null` = abre o site.
status:
type: string
enum:
- pending
- active
- error
description: >-
`pending`: falta o TXT ou o CNAME (verificando). `active`:
verificado e chegando à Cube. `error`: veja `error`.
error:
oneOf:
- type: object
required:
- code
- message
properties:
code:
type: string
enum:
- verification_expired
- domain_taken
- certificate_failed
- plan_not_allowed
message:
type: string
- type: 'null'
description: >-
`verification_expired`: sem o TXT em 7 dias. `domain_taken`: outra
conta provou a posse antes. `certificate_failed`: o HTTPS não saiu.
`plan_not_allowed`: o plano de agora não tem domínio próprio.
records:
type: array
items:
$ref: '#/components/schemas/DomainRecord'
description: Os dois registros para criar no DNS do domínio.
verifiedAt:
type:
- string
- 'null'
format: date-time
description: Quando a posse foi provada; `null` até achar o TXT.
checkedAt:
type:
- string
- 'null'
format: date-time
description: A última conferência.
createdAt:
type: string
format: date-time
project:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: string
const: error
code:
type: string
description: Código fixo em inglês. Veja [Códigos de erro](/errors).
message:
type: string
description: Texto em português para mostrar a uma pessoa.
additionalProperties: true
DomainRecord:
type: object
required:
- type
- name
- value
- isOk
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
description: >-
O nome do registro. O TXT fica em `_cube-verify.`: o `www` e a raiz usam o mesmo.
value:
type: string
description: >-
O valor: `domains.cubehost.dev` no CNAME; `cube-verify=` no
TXT.
isOk:
type: boolean
description: Se a Cube já achou o registro certo.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
Mande como `Authorization: Bearer cube_…`.
````