CNF API · v1

Visão geral

A versão 1 disponibiliza operações de DNS para zonas que você reivindicou pelo Gerenciamento de DNS. Crie e revogue tokens em Conta → Chaves de API.

URL base e versionamento

https://api.c.nf/v1

Todos os endpoints ficam abaixo de /v1. Alterações incompatíveis usarão um novo caminho de versão principal. Campos e endpoints retrocompatíveis podem ser adicionados à v1 e serão registrados no histórico de alterações.

Autenticação e escopos

Toda requisição que leia ou altere dados da conta deve incluir um token Bearer. Os tokens começam com cnf_, seguido de 32 caracteres hexadecimais.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Os tokens são armazenados como hashes unidirecionais, e o valor completo é exibido somente quando o token é criado. Se você perder um token, revogue-o e crie outro.

Cada token tem escopos. Um token sem escopo configurado recebe dns:read por padrão. O escopo de gravação também permite leituras.

Uma incompatibilidade retorna 403 forbidden_scope e inclui required_scopes e token_scopes para diagnóstico.

Isolamento por usuário

Um token Bearer corresponde a exatamente um user_id. Toda operação de zona verifica a reivindicação confirmada desse usuário antes de qualquer leitura ou gravação. Não existe exceção administrativa, mecanismo de personificação nem desvio entre usuários.

Mesmo um token com * só pode atuar em zonas verificadas por seu próprio usuário. Tentar usar a zona de outra conta retorna 403 forbidden_zone.

Envelope de resposta

Resposta bem-sucedida

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

Resposta de erro

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id aparece em todas as respostas e pode ser registrado com segurança nos logs do cliente.

Códigos de erro

Verificação de zona

Quando POST /v1/dns/zones reivindica uma zona, o servidor escolhe um destes caminhos:

1. Verificação instantânea (method: "auto") — Usada quando nenhuma outra conta reivindicou a zona. A reivindicação é verificada imediatamente. Os registros só se tornam autoritativos depois que o proprietário aponta a delegação NS no registrador para os servidores de nomes retornados.
2. Verificação por TXT — Usada para uma reivindicação contestada. Adicione o valor TXT retornado em _cnfdns-verify.<zone> e chame POST /v1/dns/zones/{zone}/verify.
3. Verificação NS legada — Reivindicações pendentes mais antigas podem usar verify_method: "ns". A verificação compara as respostas NS ativas da zona com o conjunto esperado de servidores de nomes.

A verificação é idempotente. Repeti-la para uma reivindicação verificada retorna verified: true sem alterar a reivindicação.

Tipos de registro e limites

Tipos de registro aceitos

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority é obrigatório para MX e SRV e ignorado para os outros tipos. ttl deve estar entre 60 e 2.592.000 segundos.

Endpoints da API

Serviços públicos

Endpoints pequenos e confiáveis que dispensam conta: hora, endereço, país, câmbio e hashes.

Conta

De quem é o token e o que ele pode fazer.

DNS

Reivindique um domínio, comprove que o controla e gerencie os registros.

Credenciais

O cofre privado de credenciais por trás da ferramenta de credenciais.

Arquivos

Armazenamento pessoal: listar, enviar, editar, compartilhar e excluir.

CDN

Cache na borda e tráfego dos arquivos que você compartilha.

Encaminhamento de SMS

Mensagens retransmitidas do seu telefone e as chaves que permitem isso.

Sites estáticos

Envie um zip e sirva um site.

Implantações

Os endpoints de formulário, webhook e link curto que você publicou.

Domínios

Sua carteira de domínios e os dados de registro.

Pacotes

Publique versões e consulte suas versões e totais de download.

WHOIS

Dados de registro de um domínio, em cache e compartilhados com as ferramentas de domínio.

Para agentes de IA

Aponte um agente para /v1/ai e obtenha um resumo feito para colar direto em um prompt, ou para /v1/ai?format=json e receber os mesmos endpoints como definições de ferramentas. /v1/openapi.json é o contrato OpenAPI 3.1 completo e /llms.txt é o mapa para rastreadores. Os quatro são gerados a partir da mesma tabela de rotas desta página, então nenhum deles descreve um endpoint que não existe.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

Campos da requisição

Criar uma reivindicação de zona

Criar um registro DNS

Atualizar um registro DNS

Exemplos

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Início rápido

1. Crie uma chave de API com dns:write em Conta → Chaves de API e copie-a quando ela for exibida.
2. Armazene o token em uma variável de ambiente protegida em sua máquina.
3. Chame GET /v1/account/me para confirmar o token e seus escopos.
4. Reivindique uma zona. A resposta informa se a verificação é instantânea, baseada em TXT ou baseada em NS legado.
5. Conclua a prova DNS retornada quando ela for necessária e chame o endpoint de verificação.
6. Crie, leia, atualize ou exclua registros somente depois que a reivindicação for verificada.

Registro de alterações

v1.1.0 — gerenciamento de zonas

• Adicionadas reivindicações de zona pela API, incluindo os caminhos de verificação instantânea e por TXT.
• Adicionados endpoints de status de zona individual e de verificação idempotente.
• Adicionada a revogação de reivindicações sem exclusão implícita de registros.
• Adicionados filtros de verificadas, pendentes e todas à lista de zonas.

v1.0.0 — versão inicial

• Adicionadas autenticação por token Bearer e isolamento de zonas por usuário.
• Adicionados escopos de leitura e gravação.
• Adicionados endpoints de conta, lista de zonas e gerenciamento de registros.
• Adicionado um envelope de resposta consistente com um identificador de requisição.