CNF API · v1

Descripción general

La versión 1 expone operaciones DNS para las zonas que haya reclamado mediante Administración de DNS. Cree y revoque tokens en Cuenta → Claves de API.

URL base y versiones

https://api.c.nf/v1

Todos los endpoints se encuentran bajo /v1. Los cambios incompatibles usarán una ruta de nueva versión principal. Se pueden añadir campos y endpoints compatibles con versiones anteriores a v1, que se anotarán en el registro de cambios.

Autenticación y ámbitos

Cada solicitud que lea o modifique datos de una cuenta debe incluir un token Bearer. Los tokens comienzan por cnf_ seguido de 32 caracteres hexadecimales.

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

Los tokens se guardan como hashes unidireccionales y el valor completo solo se muestra al crearlo. Si pierde un token, revóquelo y cree otro.

Cada token contiene ámbitos. Un token sin ámbitos configurados recibe dns:read de forma predeterminada. El ámbito de escritura también permite leer.

Una discrepancia devuelve 403 forbidden_scope e incluye tanto required_scopes como token_scopes para facilitar el diagnóstico.

Aislamiento por usuario

Un token Bearer se asocia con exactamente un user_id. Cada controlador de zona comprueba la reclamación verificada de ese usuario antes de cualquier lectura o escritura. No existe ninguna excepción para administradores, ruta de suplantación ni forma de eludir el aislamiento entre usuarios.

Incluso un token con * solo puede actuar sobre las zonas verificadas de su propio usuario. Intentar usar la zona de otra cuenta devuelve 403 forbidden_zone.

Estructura de respuesta

Respuesta correcta

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

Respuesta de error

{
  "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 en todas las respuestas y puede registrarse de forma segura en los registros del cliente.

Códigos de error

Verificación de zonas

Cuando POST /v1/dns/zones reclama una zona, el servidor elige una de estas vías:

1. Verificación instantánea (method: "auto") — Se usa cuando ninguna otra cuenta ha reclamado la zona. La reclamación se verifica de inmediato. Los registros solo pasan a ser autoritativos después de que el propietario dirija la delegación NS del registrador a los servidores de nombres devueltos.
2. Verificación mediante TXT — Se usa para una reclamación disputada. Añada el valor TXT devuelto en _cnfdns-verify.<zone> y llame después a POST /v1/dns/zones/{zone}/verify.
3. Verificación NS antigua — Las reclamaciones pendientes antiguas pueden usar verify_method: "ns". La verificación compara las respuestas NS activas de la zona con el conjunto esperado de servidores de nombres.

La verificación es idempotente. Repetirla para una reclamación verificada devuelve verified: true sin cambiar la reclamación.

Tipos de registro y límites

Tipos de registro admitidos

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

priority es obligatorio para MX y SRV, y se ignora para los demás tipos. ttl debe estar entre 60 y 2.592.000 segundos.

Puntos de conexión

Servicios públicos

Endpoints pequeños y fiables que no requieren cuenta: hora, dirección, país, tipos de cambio y hashes.

Cuenta

A quién pertenece un token y qué puede hacer.

DNS

Reclama un dominio, demuestra que lo controlas y gestiona sus registros.

Credenciales

El almacén privado de credenciales que hay detrás de la herramienta de credenciales.

Archivos

Almacenamiento personal de archivos: listar, subir, editar, compartir y eliminar.

CDN

Caché en el borde y tráfico de los archivos que compartes.

Reenvío de SMS

Mensajes retransmitidos desde tu teléfono y las claves que lo permiten.

Sitios estáticos

Sube un zip y sirve un sitio.

Despliegues

Los endpoints de formulario, webhook y enlace corto que has desplegado.

Dominios

Tu cartera de dominios y sus datos de registro.

Paquetes

Publica versiones y consulta sus versiones y totales de descargas.

WHOIS

Datos de registro de un dominio, en caché y compartidos con las herramientas de dominios.

Para agentes de IA

Dirige un agente a /v1/ai para obtener un resumen pensado para pegarlo en un prompt, o a /v1/ai?format=json para los mismos endpoints como definiciones de herramientas. /v1/openapi.json es el contrato OpenAPI 3.1 completo y /llms.txt es el mapa para rastreadores. Los cuatro se generan a partir de la misma tabla de rutas que esta página, así que ninguno puede describir un endpoint que no 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 de solicitud

Crear una reclamación de zona

Crear un registro DNS

Actualizar un registro DNS

Ejemplos

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"}'

Inicio rápido

1. Cree una clave de API con dns:write en Cuenta → Claves de API y cópiela cuando se muestre.
2. Guarde el token en una variable de entorno protegida de su equipo.
3. Llame a GET /v1/account/me para confirmar el token y sus ámbitos.
4. Reclame una zona. La respuesta indica si la verificación es instantánea, se basa en TXT o usa el método NS antiguo.
5. Complete la prueba DNS devuelta cuando sea necesaria y llame después al endpoint de verificación.
6. Cree, lea, actualice o elimine registros solo después de verificar la reclamación.

Registro de cambios

v1.1.0 — administración de zonas

• Se añadieron reclamaciones de zonas mediante la API, incluidas las vías de verificación instantánea y mediante TXT.
• Se añadieron endpoints de estado de zona individual y verificación idempotente.
• Se añadió la revocación de reclamaciones sin eliminar implícitamente los registros.
• Se añadieron filtros de zonas verificadas, pendientes y todas a la lista de zonas.

v1.0.0 — versión inicial

• Se añadieron autenticación mediante token Bearer y aislamiento de zonas por usuario.
• Se añadieron ámbitos de lectura y escritura.
• Se añadieron endpoints de cuenta, lista de zonas y administración de registros.
• Se añadió una estructura de respuesta uniforme con un identificador de solicitud.