> ## 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.

# Atualizar zona

> Atualiza a descrição e as etiquetas de uma zona. Omita a descrição para mantê-la ou envie uma string vazia para limpá-la. As tags omitidas são deixadas sozinhas; um mapa de tags substitui o conjunto de tags da zona, então um objeto vazio o limpa.

Tags gate policy, bem como etiquetar a zona, de modo que isso é autorizado contra as tags que estão sendo solicitadas e as tags que a zona já carrega — um principal cercado a um deles é recusado pelo outro.


<Info>
  Requer a ação do IAM **`dns:UpdateZone`**. Consulte [permissões de DNS](/pt/dns/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
</Info>


## OpenAPI

````yaml /pt/api-reference/specs/dns.yaml patch /v1/zones/{zone_id}
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/{zone_id}:
    patch:
      tags:
        - DNS
      summary: Atualizar zona
      description: >
        Atualiza a descrição e as etiquetas de uma zona. Omita a descrição para
        mantê-la ou envie uma string vazia para limpá-la. As tags omitidas são
        deixadas sozinhas; um mapa de tags substitui o conjunto de tags da zona,
        então um objeto vazio o limpa.


        Tags gate policy, bem como etiquetar a zona, de modo que isso é
        autorizado contra as tags que estão sendo solicitadas e as tags que a
        zona já carrega — um principal cercado a um deles é recusado pelo outro.
      operationId: updateZone
      parameters:
        - $ref: '#/components/parameters/ZoneId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZoneUpdateRequest'
      responses:
        '200':
          description: A zona atualizada
          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'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    ZoneId:
      name: zone_id
      in: path
      description: ID da zona DNS
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    ZoneUpdateRequest:
      type: object
      description: >-
        Descrição e tags dos patches. O nome, a visibilidade e a postura DNSSEC
        são fixos na criação; os registros são seus próprios sub-recursos.
      properties:
        description:
          type: string
          description: >-
            Omita para preservar a descrição; envie uma string vazia para
            limpar.
          example: Production DNS
        tags:
          allOf:
            - $ref: '#/components/schemas/Tags'
            - description: >-
                Um mapa atual as SUBSTITUI, então envie um objeto vazio para
                limpá-las. Tags são relevantes para a política — uma instrução
                pode condicionar a basalt:ResourceTag/<key> — para que a sua
                alteração seja autorizada tanto para as etiquetas solicitadas
                como para as etiquetas já existentes na zona.
    ZoneResponse:
      type: object
      properties:
        zone:
          $ref: '#/components/schemas/Zone'
    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'
    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
    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 — `<key_tag> <algorithm>
            <digest_type> <digest>`.
          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
    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 <token>`.
        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.