> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Criar uma zona > Crie uma nova zona DNS. Os registros SOA e NS são gerados automaticamente contra a lista de servidores de nomes da plataforma; a zona é consultável imediatamente após o sucesso. Por padrão, é uma zona pública. Passe `visibility: private` mais pelo menos uma entrada `vpcs` para uma zona que resolve somente dentro dessas VPCs — uma zona privada sem VPC ou uma zona pública que carrega `vpcs` é rejeitada com 400 em vez de ser silenciosamente forçada. Requer a ação do IAM **`dns:CreateZone`**. Consulte [permissões de DNS](/pt/dns/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política. ## OpenAPI ````yaml /pt/api-reference/specs/dns.yaml post /v1/zones openapi: 3.0.3 info: title: API de DNS Basaltic version: 1.0.0 description: > Zonas hospedadas autoritativas e seus registros, assinados com DNSSEC. Uma zona só é servida quando sua propriedade é verificada; associar uma zona a uma VPC torna-a resolvível de forma privada dentro dessa rede. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://dns.basaltic.sh description: Endpoint global da API security: - BearerAuth: [] paths: /v1/zones: post: tags: - DNS summary: Criar uma zona description: > Crie uma nova zona DNS. Os registros SOA e NS são gerados automaticamente contra a lista de servidores de nomes da plataforma; a zona é consultável imediatamente após o sucesso. Por padrão, é uma zona pública. Passe `visibility: private` mais pelo menos uma entrada `vpcs` para uma zona que resolve somente dentro dessas VPCs — uma zona privada sem VPC ou uma zona pública que carrega `vpcs` é rejeitada com 400 em vez de ser silenciosamente forçada. operationId: createZone parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ZoneCreateRequest' responses: '201': description: Zona criada content: application/json: schema: $ref: '#/components/schemas/ZoneResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: > Esta conta já tem uma zona com este nome. Outra CONTA que possua o domínio não é um conflito: várias contas podem ter uma reivindicação sobre o mesmo nome, e qualquer uma que a delegação do registrador aponte é a que a serve. É assim que um domínio se move entre contas: crie a zona aqui e aponte novamente o registrador para os nameservers que ele retorna. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Chave opcional gerada pelo cliente que torna uma criação segura para reprodução. A reintentar uma solicitação com a mesma chave retorna o resultado original literalmente em vez de criar um recurso duplicado. A reutilização de uma chave com um corpo de solicitação diferente é rejeitada (422); uma solicitação cuja chave ainda está sendo processada retorna 409. Os registros são honrados por 24 horas. Use um UUID ou token exclusivo semelhante. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: ZoneCreateRequest: type: object required: - name properties: name: type: string description: >- FQDN de zona. Os nomes de recursos não devem começar com o prefixo literal crn: ou ser UUIDs (formas canônicas, compactas, entre colchetes ou urn:uuid:, em qualquer caso). example: example.com description: type: string description: Nota de forma livre armazenada e retornada na zona. example: Production apex visibility: type: string enum: - public - private default: public description: > `private` restringe a zona para as VPCs nomeadas em `vpcs` e requer pelo menos uma; `public` (o padrão) rejeita `vpcs` completamente em vez de ignorá-los. Não pode ser alterado posteriormente. example: public dnssec: type: boolean default: true description: > Assine a zona com DNSSEC. Ligado a menos que você diga o contrário, e quase todas as zonas devem deixá-lo ligado. **Desative-o somente se este domínio for servido por outro provedor de DNS ao mesmo tempo que nós.** Uma zona assinada coloca nosso registro DS no pai, e esse DS cobre apenas as respostas que assinamos — então um resolver de validação que por acaso pergunta ao outro provedor obtém uma assinatura que não pode verificar e falha na pesquisa. Cerca de metade das suas consultas, de forma imprevisível, o que é pior do que qualquer provedor sozinho. Não assinado é a única configuração que funciona para essa configuração hoje. Fixo na criação. Desativar a assinatura mais tarde interrompe o domínio até que o DS seja retirado no registrador e essa retirada tenha se propagado, o que é uma sequência que essa API não pode executar para você. example: true import_existing_records: type: boolean default: false description: > Leia os registros do domínio dos servidores de nomes que o atendem HOJE e copie-os para esta zona, antes de mover a delegação para aqui. Vale a pena perguntar quando você está migrando um domínio ativo. A delegação é a prova de propriedade, então no momento em que você aponta seu registrador para essa zona é o momento em que começamos a responder por ela — e uma zona vazia responde com nada, o que leva o site e o e-mail para baixo até que você tenha redigitado tudo. Executa-se em segundo plano; a zona é criada imediatamente. Poll GET /v1/zones/{zone_id}/record-import para o resultado. Melhor esforço, e o resultado diz o quão bom foi. Uma transferência de zona é exaustiva e quase sempre recusada; o fallback consulta uma lista de nomes comuns e não consegue encontrar um registro que não pensou em pedir. Verifique `record_import.complete` antes de desligar o seu antigo provedor. Os registros que você já criou nunca são substituídos, e os registros que esta plataforma gerencia sozinha — o SOA, a cadeia DNSSEC, os servidores de nomes da zona — nunca são importados. example: true vpcs: type: array items: type: string description: > UUIDs de VPC de propriedade da conta ou CRNs de rede/vpc nos quais a zona resolve. Nomes nulos são rejeitados com 400 porque a solicitação não corrige nenhuma região. CRNs resolvem em sua região nomeada; UUIDs pesquisam todas as regiões habilitadas para DNS. VPCs ausentes, de conta estrangeira ou de região não configurada retornam 404. Pesquisas incompletas de UUID ou identidades duplicadas de UUID regional falham com um erro de servidor. As referências são deduplicadas pelo UUID. Necessário quando visibility=private, rejeitado quando visibility=public. Mais podem ser associados mais tarde via POST /v1/zones/{zone_id}/vpc-associations. example: - c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9 tags: $ref: '#/components/schemas/Tags' ZoneResponse: type: object properties: zone: $ref: '#/components/schemas/Zone' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de erro identificando o tipo de erro example: INVALID_INPUT message: type: string description: Mensagem de erro legível pelo ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores não sensíveis opcionais para interpolação de erros localizados, codificados por código de erro. Nunca presente para erros de servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuração example: 550e8400-e29b-41d4-a716-446655440000 Tags: type: object additionalProperties: type: string example: environment: production team: backend Zone: type: object properties: id: type: string format: uuid readOnly: true example: 550e8400-e29b-41d4-a716-446655440000 crn: type: string readOnly: true description: Nome do recurso da nuvem. example: crn:dns::my-account:zone/example.com name: type: string description: >- FQDN de zona. Os nomes de recursos não devem começar com o prefixo literal crn: ou ser UUIDs (formas canônicas, compactas, entre colchetes ou urn:uuid:, em qualquer caso). example: example.com description: type: string description: Descrição de forma livre, editável com PATCH. example: Public zone for the marketing site nameservers: type: array items: type: string description: > Servidores de nomes autoritativos para a zona — o conjunto NS de vértice. Copie esta lista literalmente na configuração do servidor de nomes do seu registrador para delegar a zona à plataforma. Esses nomes são exclusivos para ESTA zona: cada um carrega um rótulo por zona, que é o que faz a delegação funcionar como uma prova de propriedade (veja `ownership`). Duas zonas para o mesmo domínio recebem nomes diferentes, e aquele que o registrador aponta é o que serve. Use-os exatamente como estão escritos — os nomes de servidor de nomes nuos da Basaltic não verificarão a zona. example: - 028t5cy4tqkff.triton.dns.basaltic.cloud - 028t5cy4tqkff.proteus.dns.basaltic.cloud soa: $ref: '#/components/schemas/SOA' visibility: type: string enum: - public - private readOnly: true description: > `public` responder nos servidores de nomes voltados para a Internet; `private` As zonas de rede respondem somente dentro das VPCs associadas a elas (consulte os pontos de extremidade de associações de vpc). example: public dnssec: $ref: '#/components/schemas/ZoneDNSSEC' tags: $ref: '#/components/schemas/Tags' ownership: $ref: '#/components/schemas/ZoneOwnership' SOA: type: object properties: primary_ns: type: string description: SOA `mname` — primeiro servidor de nomes autoritativo para a zona. example: 028t5cy4tqkff.triton.dns.basaltic.cloud admin_email: type: string format: email readOnly: true description: > SOA `rname` — o contato de operações DNS da plataforma. Carimbado no lado do servidor; não configurável pelo cliente. example: hostmaster@basaltic.sh refresh: type: integer example: 10800 retry: type: integer example: 3600 expire: type: integer example: 604800 minimum: type: integer description: Cache TTL do NXDOMAIN. example: 3600 ZoneDNSSEC: type: object description: > Estado de assinatura DNSSEC. Presente depois que o signatário inicializou a zona, que é sempre ativada para zonas criadas por meio desta API; ausente em uma zona que não é assinada. `ds_records` é o que o cliente cola no registrador pai para completar a cadeia de confiança. `rdata` é a forma de arquivo de zona do mesmo registro, para registradores que levam uma string. required: - enabled properties: enabled: type: boolean readOnly: true example: true ksk_key_tag: type: integer readOnly: true description: >- Tag de chave da chave de assinatura de chave — corresponde aos registros DS abaixo. example: 12345 zsk_key_tag: type: integer readOnly: true description: Tag da chave da chave de assinatura de zona. example: 54321 algorithm: type: integer readOnly: true description: Número do algoritmo DNSSEC. 13 = ECDSA P-256 SHA-256. example: 13 ds_records: type: array readOnly: true items: $ref: '#/components/schemas/ZoneDSRecord' ZoneOwnership: type: object description: > Prova de propriedade de domínio. Uma zona sem uma zona existente acima dela na plataforma não é resolvida até que `verified` seja verdadeiro — defina os `nameservers` da zona no seu registrador, então POST /v1/zones/{zone_id}/verify-ownership. Não há registros para publicar. Os servidores de nomes da zona possuem um rótulo exclusivo, então delegar o domínio para eles é a prova: somente quem controla o domínio em seu registrador pode fazê-lo, e os nomes não podem ser herdados de uma zona que costumava manter esse domínio. Use os próprios `nameservers` da zona e nada mais. Os nomes de nameservers da Basaltic não provam nada por si só — qualquer um pode apontar um domínio para eles — então uma delegação nomeando-os deixa a zona não verificada. Os servidores de nomes de outros provedores podem estar ao lado do seu se você hospedar o domínio em dois provedores. O que NÃO funciona é delegar para duas zonas Basaltic ao mesmo tempo: enquanto um domínio nomeia os nameservers de outra zona, bem como este, nenhum é servido, e o remédio é remover aqueles que esta zona não lista. Esse é o estado que você deve esperar a meio da transferência de um domínio entre contas. Uma zona criada abaixo de uma zona que você já possui herda a prova de seu pai e é verificada na criação. A prova é um contrato de locação, não uma escritura: é re-confirmada periodicamente enquanto a zona for servida, então um domínio que expira ou muda de mãos deixa de ser servido a partir daqui. `checked_at` é a última confirmação; `recheck_deadline` aparece apenas quando a reconfirmação está falhando e é o campo para renderizar um aviso. properties: verified: type: boolean readOnly: true description: Se a zona provou a propriedade. Zonas não verificadas não resolvem. example: false verified_at: type: string format: date-time readOnly: true nullable: true description: >- Quando a propriedade foi provada pela primeira vez. Ausente enquanto não verificado. example: '2026-01-15T09:30:00Z' checked_at: type: string format: date-time readOnly: true description: > Quando a prova foi re-confirmada pela última vez. `verified_at` mantém o significado "primeiro demonstrado" e não se move; isso acontece em cada passagem que passa. Ausente até que a zona tenha sido reconfirmada pelo menos uma vez. example: '2026-04-14T09:30:00Z' recheck_deadline: type: string format: date-time readOnly: true description: > Presente SOMENTE enquanto a reprova periódica está falhando: o instante em que a zona pára de responder, a menos que passe novamente. Ausente significa saudável. Cada passagem re-verifica uma zona de falha, então chegar a essa data leva uma falha sustentada, não uma tarde ruim — um problema de resolução transiente se limpa na próxima passagem. Para limpar deliberadamente, aponte a delegação do domínio de volta para os `nameservers` desta zona e POST /v1/zones/{zone_id}/verify-ownership. O proprietário da organização é notificado por email quando essa data é definida e novamente se a zona parar de resolver. Uma zona nunca é retirada do ar antes que essa mensagem tenha sido enviada, então a data aqui é a mais cedo que a zona pode parar de responder e nunca o único aviso. example: '2026-04-28T09:30:00Z' ZoneDSRecord: type: object description: Um registro DS para publicar na zona pai. required: - key_tag - algorithm - digest_type - digest - rdata properties: key_tag: type: integer example: 12345 algorithm: type: integer example: 13 digest_type: type: integer description: 2 = SHA-256. example: 2 digest: type: string example: B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861 rdata: type: string description: >- Forma completa de arquivo de zona — ` `. example: >- 12345 13 2 B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861 responses: BadRequest: description: Parâmetros de solicitação inválidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Autenticação necessária ou token inválido content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Permissões insuficientes content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Página não encontrada content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: > A solicitação está bem formada, mas não pode ser processada conforme enviada. Nas operações que aceitam `Idempotency-Key` este é o caso de reutilização de chave: a chave foi vista pela primeira vez com uma carga de solicitação diferente, então reproduzir o resultado armazenado responderia a uma pergunta que o chamador não fez. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Erro interno do servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `. Esta é a forma recomendada de autenticação. Obtenha o token trocando o par de chaves de acesso de uma conta de serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`. Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis com OAuth podem obter e renovar o token para você. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso também serve como credencial AWS SigV4 para o endpoint de objetos compatível com S3, que aceita somente esse método de autenticação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.