Registros DNS

Ver en Markdown

Lista, crea, modifica y borra los registros DNS de una zona, en bloque o en un lote, e importa los registros existentes.

En esta página

Registros DNS de una zona. Los A/AAAA/CNAME pueden ir con proxy: el nombre responde entonces con las direcciones del borde y el contenido del registro pasa a ser el origen. En una zona externa solo se admiten A/AAAA/CNAME con proxy (son los sitios que sirve el borde). Cada escritura crea una versión de configuración.

OperaciónRuta
Listar registrosGET /v1/orgs/{org}/zones/{zone}/records
Crear un registroPOST /v1/orgs/{org}/zones/{zone}/records
Crear registros en bloquePOST /v1/orgs/{org}/zones/{zone}/records/bulk
Lote de registrosPOST /v1/orgs/{org}/zones/{zone}/records/batch
Ver un registroGET /v1/orgs/{org}/zones/{zone}/records/{record}
Modificar un registroPATCH /v1/orgs/{org}/zones/{zone}/records/{record}
Borrar un registroDELETE /v1/orgs/{org}/zones/{zone}/records/{record}
Buscar los registros existentesGET /v1/orgs/{org}/zones/{zone}/import
Leer un fichero de zona BINDPOST /v1/orgs/{org}/zones/{zone}/import/bind
Ver las respuestas DNS del bordeGET /v1/orgs/{org}/zones/{zone}/dns/answers

Listar registros

GET /v1/orgs/{org}/zones/{zone}/records

Lista los registros DNS de una zona con sus ids.

Rol necesario: readonly o superior.

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).

Respuesta

  • 200: Devuelve items, un array de Record.
CampoTipoDescripción
items[].idstring (uuid)Id.
items[].org_idstring (uuid)Id de la organización.
items[].zone_idstring (uuid)Id de la zona.
items[].typestring
items[].namestringNombre completo sin punto final.
items[].contentstringContenido de origen.
items[].ttlintegerTTL en segundos.
items[].priorityintegerPrioridad de MX y SRV (null en los demás tipos).
items[].proxiedbooleanServido a través del borde de OpenWAF.
items[].commentstringComentario (vacío si no hay).
items[].tagsarray de stringEtiquetas (lista vacía si no hay).
items[].created_atstring (date-time)Fecha de creación.
items[].updated_atstring (date-time)Último cambio.

Ejemplo

curl "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
200
{
  "items": [
    {
      "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
      "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
      "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
      "type": "A",
      "name": "www.example.com",
      "content": "203.0.113.10",
      "ttl": 300,
      "priority": null,
      "proxied": true,
      "comment": "Web servers",
      "tags": [
        "web"
      ],
      "created_at": "2026-03-02T10:25:00Z",
      "updated_at": "2026-10-27T09:00:00Z"
    }
  ]
}

Crear un registro

POST /v1/orgs/{org}/zones/{zone}/records

Crea un registro DNS. En una zona externa solo se admiten A/AAAA/CNAME con proxy (son los sitios que se publican al borde); no se publican en el DNS, que sigue en el otro proveedor.

Rol necesario: tech o superior.

Controles de cambio: dry_run · If-Match (opcional) · X-Change-Reason (obligatorio)

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
X-Change-ReasoncabecerastringSíMotivo del cambio: 1-500 caracteres UTF-8 tras recortar espacios, sin caracteres de control. Si falta o no es válido: 422 reason_required. De 1 a 500 caracteres.
If-MatchcabecerastringNoVersión de configuración esperada, p. ej. "12" (se admite W/). Si no es la actual: 412 version_conflict.
dry_runconsultastringNo1/true simula el cambio: responde 200 con el plan (Applied) y no guarda nada. Admite 0/false; otro valor: 400. Uno de 1, true, 0, false.

Cuerpo de la petición

Tipo de contenido application/json. Esquema: RecordInput.

CampoTipoObligatorioDescripción
typestringSíUno de A, AAAA, CNAME, MX, TXT, NS, SRV, CAA.
namestringNo@, relativo (www) o nombre completo; * para comodín. Por defecto @.
contentstringSíA/AAAA: dirección. CNAME/NS/MX: nombre de host. TXT: texto sin comillas (se trocea en cadenas de 255). SRV: peso puerto destino. CAA: flags etiqueta "valor".
ttlintegerNoTTL en segundos. Por defecto 3600. De 60 a 86400.
priorityintegerNoObligatoria en MX y SRV; prohibida en el resto. De 0 a 65535.
proxiedbooleanNoSolo A/AAAA/CNAME. El nombre responde con las IPs del borde (TTL 300) y el contenido se guarda como origen. Todos los A/AAAA/CNAME de un nombre comparten el valor. Un CNAME sin proxy en el apex se publica como ALIAS (aplanado). Por defecto false.
commentstringNoAtributo del registro (no se publica en el DNS; entra en las versiones de la zona). Sin caracteres de control. Como mucho 100 caracteres.
tagsarray de stringNoAtributo del registro, como el comentario. Se pasan a minúsculas y se quitan las repetidas. Como mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.

Respuesta

  • 200: Con dry_run=1, el plan del cambio (Applied); no se guarda nada.
  • 201: Creado y publicado. Devuelve Record.
CampoTipoDescripción
idstring (uuid)Id.
org_idstring (uuid)Id de la organización.
zone_idstring (uuid)Id de la zona.
typestring
namestringNombre completo sin punto final.
contentstringContenido de origen.
ttlintegerTTL en segundos.
priorityintegerPrioridad de MX y SRV (null en los demás tipos).
proxiedbooleanServido a través del borde de OpenWAF.
commentstringComentario (vacío si no hay).
tagsarray de stringEtiquetas (lista vacía si no hay).
created_atstring (date-time)Fecha de creación.
updated_atstring (date-time)Último cambio.

Cabeceras de la respuesta: ETag, X-Config-Version.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
409Zona desactivada o zone_merged.
412version_conflict: If-Match no coincide con la versión actual.
422Error de validación (invalid) o motivo ausente/no válido (reason_required).

Ejemplo

curl -X POST "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "X-Change-Reason: Add the API host" \
  -H 'If-Match: "12"' \
  -H "Content-Type: application/json" \
  --data '{
    "type": "A",
    "name": "api",
    "content": "203.0.113.20",
    "proxied": true
  }'
201
{
  "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
  "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
  "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
  "type": "A",
  "name": "www.example.com",
  "content": "203.0.113.10",
  "ttl": 300,
  "priority": null,
  "proxied": true,
  "comment": "Web servers",
  "tags": [
    "web"
  ],
  "created_at": "2026-03-02T10:25:00Z",
  "updated_at": "2026-10-27T09:00:00Z"
}

Crear registros en bloque

POST /v1/orgs/{org}/zones/{zone}/records/bulk

Crea hasta 1000 registros de forma atómica, todos o ninguno, en una sola versión (por ejemplo una importación revisada). Un error de validación indica el registro en field (records[i].campo).

Rol necesario: tech o superior.

Controles de cambio: dry_run · If-Match (opcional) · X-Change-Reason (obligatorio)

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
X-Change-ReasoncabecerastringSíMotivo del cambio: 1-500 caracteres UTF-8 tras recortar espacios, sin caracteres de control. Si falta o no es válido: 422 reason_required. De 1 a 500 caracteres.
If-MatchcabecerastringNoVersión de configuración esperada, p. ej. "12" (se admite W/). Si no es la actual: 412 version_conflict.
dry_runconsultastringNo1/true simula el cambio: responde 200 con el plan (Applied) y no guarda nada. Admite 0/false; otro valor: 400. Uno de 1, true, 0, false.

Cuerpo de la petición

Tipo de contenido application/json.

CampoTipoObligatorioDescripción
recordsarray de RecordInputSíComo mucho 1000 elementos.
records[].typestringSíUno de A, AAAA, CNAME, MX, TXT, NS, SRV, CAA.
records[].namestringNo@, relativo (www) o nombre completo; * para comodín. Por defecto @.
records[].contentstringSíA/AAAA: dirección. CNAME/NS/MX: nombre de host. TXT: texto sin comillas (se trocea en cadenas de 255). SRV: peso puerto destino. CAA: flags etiqueta "valor".
records[].ttlintegerNoTTL en segundos. Por defecto 3600. De 60 a 86400.
records[].priorityintegerNoObligatoria en MX y SRV; prohibida en el resto. De 0 a 65535.
records[].proxiedbooleanNoSolo A/AAAA/CNAME. El nombre responde con las IPs del borde (TTL 300) y el contenido se guarda como origen. Todos los A/AAAA/CNAME de un nombre comparten el valor. Un CNAME sin proxy en el apex se publica como ALIAS (aplanado). Por defecto false.
records[].commentstringNoAtributo del registro (no se publica en el DNS; entra en las versiones de la zona). Sin caracteres de control. Como mucho 100 caracteres.
records[].tagsarray de stringNoAtributo del registro, como el comentario. Se pasan a minúsculas y se quitan las repetidas. Como mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.

Respuesta

  • 200: Con dry_run=1, el plan del cambio (Applied); no se guarda nada.
  • 201: Creados (una sola versión). Devuelve items, un array de Record.
CampoTipoDescripción
items[].idstring (uuid)Id.
items[].org_idstring (uuid)Id de la organización.
items[].zone_idstring (uuid)Id de la zona.
items[].typestring
items[].namestringNombre completo sin punto final.
items[].contentstringContenido de origen.
items[].ttlintegerTTL en segundos.
items[].priorityintegerPrioridad de MX y SRV (null en los demás tipos).
items[].proxiedbooleanServido a través del borde de OpenWAF.
items[].commentstringComentario (vacío si no hay).
items[].tagsarray de stringEtiquetas (lista vacía si no hay).
items[].created_atstring (date-time)Fecha de creación.
items[].updated_atstring (date-time)Último cambio.

Cabeceras de la respuesta: ETag, X-Config-Version.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
409zone_merged: la zona está fusionada en otra (solo lectura hasta que se separe o se purgue).
412version_conflict: If-Match no coincide con la versión actual.
422Error de validación (field indica records[i].campo) o reason_required.

Ejemplo

curl -X POST "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records/bulk" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "X-Change-Reason: Import reviewed records" \
  -H "Content-Type: application/json" \
  --data '{
    "records": [
      {
        "type": "A",
        "name": "@",
        "content": "203.0.113.10",
        "proxied": true
      },
      {
        "type": "MX",
        "name": "@",
        "content": "mail.example.com",
        "priority": 10
      }
    ]
  }'
201
{
  "items": [
    {
      "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
      "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
      "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
      "type": "A",
      "name": "www.example.com",
      "content": "203.0.113.10",
      "ttl": 300,
      "priority": null,
      "proxied": true,
      "comment": "Web servers",
      "tags": [
        "web"
      ],
      "created_at": "2026-03-02T10:25:00Z",
      "updated_at": "2026-10-27T09:00:00Z"
    }
  ]
}

Lote de registros

POST /v1/orgs/{org}/zones/{zone}/records/batch

Crea, modifica y borra registros como un único cambio, todo o nada, con una sola versión, un solo motivo y una entrada de auditoría por registro. Activar o desactivar el proxy de un A/AAAA/CNAME cambia también los demás A/AAAA/CNAME del mismo nombre que no estén en el lote. La respuesta (200) es el plan del cambio más los registros de la zona resultantes.

Rol necesario: tech o superior.

Controles de cambio: dry_run · If-Match (opcional) · X-Change-Reason (obligatorio)

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
X-Change-ReasoncabecerastringSíMotivo del cambio: 1-500 caracteres UTF-8 tras recortar espacios, sin caracteres de control. Si falta o no es válido: 422 reason_required. De 1 a 500 caracteres.
If-MatchcabecerastringNoVersión de configuración esperada, p. ej. "12" (se admite W/). Si no es la actual: 412 version_conflict.
dry_runconsultastringNo1/true simula el cambio: responde 200 con el plan (Applied) y no guarda nada. Admite 0/false; otro valor: 400. Uno de 1, true, 0, false.

Cuerpo de la petición

Tipo de contenido application/json. Esquema: RecordBatch.

Hasta 500 operaciones en total. Cada registro se actualiza o borra una sola vez. Se aplican los borrados, luego las actualizaciones y luego las altas; las reglas de convivencia se comprueban sobre el estado final.

CampoTipoObligatorioDescripción
createarray de RecordInputNo
create[].typestringSíUno de A, AAAA, CNAME, MX, TXT, NS, SRV, CAA.
create[].namestringNo@, relativo (www) o nombre completo; * para comodín. Por defecto @.
create[].contentstringSíA/AAAA: dirección. CNAME/NS/MX: nombre de host. TXT: texto sin comillas (se trocea en cadenas de 255). SRV: peso puerto destino. CAA: flags etiqueta "valor".
create[].ttlintegerNoTTL en segundos. Por defecto 3600. De 60 a 86400.
create[].priorityintegerNoObligatoria en MX y SRV; prohibida en el resto. De 0 a 65535.
create[].proxiedbooleanNoSolo A/AAAA/CNAME. El nombre responde con las IPs del borde (TTL 300) y el contenido se guarda como origen. Todos los A/AAAA/CNAME de un nombre comparten el valor. Un CNAME sin proxy en el apex se publica como ALIAS (aplanado). Por defecto false.
create[].commentstringNoAtributo del registro (no se publica en el DNS; entra en las versiones de la zona). Sin caracteres de control. Como mucho 100 caracteres.
create[].tagsarray de stringNoAtributo del registro, como el comentario. Se pasan a minúsculas y se quitan las repetidas. Como mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.
updatearray de objetoNo
update[].idstring (uuid)SíId.
update[].typestringNo
update[].namestringNoNombre.
update[].contentstringNo
update[].ttlintegerNoTTL en segundos.
update[].priorityinteger o nullNoPrioridad de MX y SRV (null en los demás tipos).
update[].proxiedbooleanNoServido a través del borde de OpenWAF.
update[].commentstringNoComo mucho 100 caracteres.
update[].tagsarray de stringNoComo mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.
deletearray de string (uuid)No

Respuesta

  • 200: Aplicado (o simulado con dry_run). Devuelve BatchResult.
CampoTipoDescripción
dry_runbooleantrue en una simulación.
from_versionintegerVersión actual antes del cambio.
to_versionintegerVersión que crea el cambio (la misma si no cambia nada).
diffDiffCambios.
warningsarray de stringAvisos (el cambio sigue siendo válido).
recordsarray de RecordRegistros de la zona tras el cambio (simulado con dry_run).

Cabeceras de la respuesta: ETag, X-Config-Version.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
409Zona desactivada o zone_merged.
412version_conflict: If-Match no coincide con la versión actual.
422Error de validación (field indica la operación: create[i].campo, update[i].campo, delete[i]; vacío si el lote está vacío o supera 500 operaciones) o reason_required.

Ejemplo

curl -X POST "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records/batch?dry_run=1" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "X-Change-Reason: Move the site to the new origin" \
  -H "Content-Type: application/json" \
  --data '{
    "create": [
      {
        "type": "CNAME",
        "name": "shop",
        "content": "shops.example.net",
        "proxied": true
      }
    ],
    "update": [
      {
        "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
        "content": "203.0.113.30"
      }
    ],
    "delete": [
      "1b3d5f7a-9c2e-4a6b-8d0f-2a4c6e8b0d2f"
    ]
  }'
200
{
  "dry_run": false,
  "from_version": 12,
  "to_version": 12,
  "diff": {
    "from": 0,
    "to": 0,
    "changes": [
      {
        "path": "rules[id=12]",
        "op": "add",
        "from": "example",
        "to": "example"
      }
    ]
  },
  "warnings": [],
  "records": [
    {
      "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
      "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
      "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
      "type": "A",
      "name": "www.example.com",
      "content": "203.0.113.10",
      "ttl": 300,
      "priority": null,
      "proxied": true,
      "comment": "Web servers",
      "tags": [
        "web"
      ],
      "created_at": "2026-03-02T10:25:00Z",
      "updated_at": "2026-10-27T09:00:00Z"
    }
  ]
}

Ver un registro

GET /v1/orgs/{org}/zones/{zone}/records/{record}

Devuelve un registro. En un registro con proxy, content es el origen.

Rol necesario: readonly o superior.

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
recordrutastring (uuid)SíId del registro (consulta Listar registros).

Respuesta

CampoTipoDescripción
idstring (uuid)Id.
org_idstring (uuid)Id de la organización.
zone_idstring (uuid)Id de la zona.
typestring
namestringNombre completo sin punto final.
contentstringContenido de origen.
ttlintegerTTL en segundos.
priorityintegerPrioridad de MX y SRV (null en los demás tipos).
proxiedbooleanServido a través del borde de OpenWAF.
commentstringComentario (vacío si no hay).
tagsarray de stringEtiquetas (lista vacía si no hay).
created_atstring (date-time)Fecha de creación.
updated_atstring (date-time)Último cambio.

Errores

EstadoDescripción
404No existe o el token no lo ve (not_found).

Ejemplo

curl "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records/0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
200
{
  "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
  "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
  "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
  "type": "A",
  "name": "www.example.com",
  "content": "203.0.113.10",
  "ttl": 300,
  "priority": null,
  "proxied": true,
  "comment": "Web servers",
  "tags": [
    "web"
  ],
  "created_at": "2026-03-02T10:25:00Z",
  "updated_at": "2026-10-27T09:00:00Z"
}

Modificar un registro

PATCH /v1/orgs/{org}/zones/{zone}/records/{record}

Cambia campos de un registro; los campos ausentes conservan su valor.

Rol necesario: tech o superior.

Controles de cambio: dry_run · If-Match (opcional) · X-Change-Reason (obligatorio)

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
recordrutastring (uuid)SíId del registro (consulta Listar registros).
X-Change-ReasoncabecerastringSíMotivo del cambio: 1-500 caracteres UTF-8 tras recortar espacios, sin caracteres de control. Si falta o no es válido: 422 reason_required. De 1 a 500 caracteres.
If-MatchcabecerastringNoVersión de configuración esperada, p. ej. "12" (se admite W/). Si no es la actual: 412 version_conflict.
dry_runconsultastringNo1/true simula el cambio: responde 200 con el plan (Applied) y no guarda nada. Admite 0/false; otro valor: 400. Uno de 1, true, 0, false.

Cuerpo de la petición

Tipo de contenido application/json. Esquema: RecordPatch.

Campos que cambian; los ausentes se conservan.

CampoTipoObligatorioDescripción
typestringNo
namestringNoNombre.
contentstringNo
ttlintegerNoTTL en segundos.
priorityinteger o nullNoPrioridad de MX y SRV (null en los demás tipos).
proxiedbooleanNoServido a través del borde de OpenWAF.
commentstringNoComo mucho 100 caracteres.
tagsarray de stringNoComo mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.

Respuesta

  • 200: Registro modificado (con X-Config-Version y ETag) o, con dry_run, el plan (Applied). Devuelve Record o Applied.
CampoTipoDescripción
idstring (uuid)Id.
org_idstring (uuid)Id de la organización.
zone_idstring (uuid)Id de la zona.
typestring
namestringNombre completo sin punto final.
contentstringContenido de origen.
ttlintegerTTL en segundos.
priorityintegerPrioridad de MX y SRV (null en los demás tipos).
proxiedbooleanServido a través del borde de OpenWAF.
commentstringComentario (vacío si no hay).
tagsarray de stringEtiquetas (lista vacía si no hay).
created_atstring (date-time)Fecha de creación.
updated_atstring (date-time)Último cambio.

Cabeceras de la respuesta: ETag, X-Config-Version.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
409zone_merged: la zona está fusionada en otra (solo lectura hasta que se separe o se purgue).
412version_conflict: If-Match no coincide con la versión actual.
422Error de validación (invalid) o motivo ausente/no válido (reason_required).

Ejemplo

curl -X PATCH "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records/0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "X-Change-Reason: Point www at the new origin" \
  -H 'If-Match: "12"' \
  -H "Content-Type: application/json" \
  --data '{
    "content": "203.0.113.30"
  }'
200
{
  "id": "0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d",
  "org_id": "1e7c9a3b-5d2f-4b8a-9c6e-0f2a4b6c8d1e",
  "zone_id": "6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d",
  "type": "A",
  "name": "www.example.com",
  "content": "203.0.113.10",
  "ttl": 300,
  "priority": null,
  "proxied": true,
  "comment": "Web servers",
  "tags": [
    "web"
  ],
  "created_at": "2026-03-02T10:25:00Z",
  "updated_at": "2026-10-27T09:00:00Z"
}

Borrar un registro

DELETE /v1/orgs/{org}/zones/{zone}/records/{record}

Borra un registro. Borrar un registro con proxy deja de servir su sitio.

Rol necesario: tech o superior.

Controles de cambio: dry_run · If-Match (opcional) · X-Change-Reason (obligatorio)

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
recordrutastring (uuid)SíId del registro (consulta Listar registros).
X-Change-ReasoncabecerastringSíMotivo del cambio: 1-500 caracteres UTF-8 tras recortar espacios, sin caracteres de control. Si falta o no es válido: 422 reason_required. De 1 a 500 caracteres.
If-MatchcabecerastringNoVersión de configuración esperada, p. ej. "12" (se admite W/). Si no es la actual: 412 version_conflict.
dry_runconsultastringNo1/true simula el cambio: responde 200 con el plan (Applied) y no guarda nada. Admite 0/false; otro valor: 400. Uno de 1, true, 0, false.

Respuesta

  • 200: Con dry_run=1, el plan del cambio (Applied); no se guarda nada.
  • 204: Borrado. Sin cuerpo.

Cabeceras de la respuesta: ETag, X-Config-Version.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
404No existe o el token no lo ve (not_found).
409zone_merged: la zona está fusionada en otra (solo lectura hasta que se separe o se purgue).
412version_conflict: If-Match no coincide con la versión actual.
422Error de validación (invalid) o motivo ausente/no válido (reason_required).

Ejemplo

curl -X DELETE "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/records/0c9a7e4d-2b1f-4e6a-8d3c-5f7b9a1c3e5d" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "X-Change-Reason: Remove an unused host" \
  -H 'If-Match: "12"'

Buscar los registros existentes

GET /v1/orgs/{org}/zones/{zone}/import

Consulta a los servidores autoritativos actuales (o a resolvedores públicos) el ápice, los nombres habituales, los TXT de correo, los SRV y los nombres vistos en los registros de Certificate Transparency, y los devuelve para revisarlos. No aplica nada; la lista revisada se envía a Crear registros en bloque o a Lote de registros.

Rol necesario: tech o superior.

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).

Respuesta

CampoTipoDescripción
domainstring
serversarray de string
wildcardboolean
warningsarray de stringAvisos (el cambio sigue siendo válido).
candidatesarray de objeto
candidates[].typestringUno de A, AAAA, CNAME, MX, TXT, NS, SRV, CAA.
candidates[].namestring@, relativo (www) o nombre completo; * para comodín. Por defecto @.
candidates[].contentstringA/AAAA: dirección. CNAME/NS/MX: nombre de host. TXT: texto sin comillas (se trocea en cadenas de 255). SRV: peso puerto destino. CAA: flags etiqueta "valor".
candidates[].ttlintegerTTL en segundos. Por defecto 3600. De 60 a 86400.
candidates[].priorityintegerObligatoria en MX y SRV; prohibida en el resto. De 0 a 65535.
candidates[].proxiedbooleanSolo A/AAAA/CNAME. El nombre responde con las IPs del borde (TTL 300) y el contenido se guarda como origen. Todos los A/AAAA/CNAME de un nombre comparten el valor. Un CNAME sin proxy en el apex se publica como ALIAS (aplanado). Por defecto false.
candidates[].commentstringAtributo del registro (no se publica en el DNS; entra en las versiones de la zona). Sin caracteres de control. Como mucho 100 caracteres.
candidates[].tagsarray de stringAtributo del registro, como el comentario. Se pasan a minúsculas y se quitan las repetidas. Como mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.
candidates[].sourcestringUno de dns, crtsh.

Ejemplo

curl "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/import" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
200
{
  "domain": "example",
  "servers": [
    "example"
  ],
  "wildcard": false,
  "warnings": [],
  "candidates": [
    {
      "type": "A",
      "name": "example.com",
      "content": "203.0.113.10",
      "ttl": 3600,
      "priority": 0,
      "proxied": false,
      "comment": "Web servers",
      "tags": [
        "web"
      ],
      "source": "dns"
    }
  ]
}

Leer un fichero de zona BIND

POST /v1/orgs/{org}/zones/{zone}/import/bind

Lee un fichero de zona BIND (de hasta 1 MiB) y devuelve sus registros para revisarlos. No aplica nada; los candidatos elegidos se aplican con Lote de registros. No disponible en zonas externas.

Entiende $ORIGIN, $TTL, @, nombres relativos, dueños heredados, paréntesis, comentarios y TXT de varias cadenas. Deja fuera, con su motivo, el SOA y los NS del ápice (los pone OpenWAF), otras directivas, tipos o clases no admitidos, nombres fuera de la zona, registros no válidos, los que ya existen en la zona y los repetidos.

Rol necesario: tech o superior.

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).
proxiedconsultabooleanNoCon proxy los A/AAAA/CNAME cuyo nombre puede ser un sitio (ni comodines ni _). Por defecto false.

Cuerpo de la petición

Tipo de contenido text/plain.

Como mucho 1048576 caracteres.

Respuesta

CampoTipoDescripción
itemsarray de objeto
items[].typestringUno de A, AAAA, CNAME, MX, TXT, NS, SRV, CAA.
items[].namestring@, relativo (www) o nombre completo; * para comodín. Por defecto @.
items[].contentstringA/AAAA: dirección. CNAME/NS/MX: nombre de host. TXT: texto sin comillas (se trocea en cadenas de 255). SRV: peso puerto destino. CAA: flags etiqueta "valor".
items[].ttlintegerTTL en segundos. Por defecto 3600. De 60 a 86400.
items[].priorityintegerObligatoria en MX y SRV; prohibida en el resto. De 0 a 65535.
items[].proxiedbooleanSolo A/AAAA/CNAME. El nombre responde con las IPs del borde (TTL 300) y el contenido se guarda como origen. Todos los A/AAAA/CNAME de un nombre comparten el valor. Un CNAME sin proxy en el apex se publica como ALIAS (aplanado). Por defecto false.
items[].commentstringAtributo del registro (no se publica en el DNS; entra en las versiones de la zona). Sin caracteres de control. Como mucho 100 caracteres.
items[].tagsarray de stringAtributo del registro, como el comentario. Se pasan a minúsculas y se quitan las repetidas. Como mucho 10 elementos. Elementos con el patrón ^[a-z0-9][a-z0-9:_-]{0,31}$.
items[].sourcestringSiempre file.
skippedarray de objectComo mucho 200 entradas; skipped_total las cuenta todas.
skipped[].lineintegerLínea donde empieza la entrada.
skipped[].textstringEntrada sin comentarios (hasta 200 bytes).
skipped[].reasonstringMotivo del cambio.
skipped_totalintegerEntradas dejadas fuera (todas, aunque skipped liste solo las 200 primeras).
truncatedbooleanEl fichero tenía más de 5000 entradas: solo se han leído las primeras 5000.

Errores

EstadoDescripción
400Petición mal formada (bad_request).
404No existe o el token no lo ve (not_found).
409Zona externa.
413too_large: el fichero pasa de 1 MiB.

Ejemplo

curl -X POST "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/import/bind" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @example.com.zone
200
{
  "items": [
    {
      "type": "A",
      "name": "example.com",
      "content": "203.0.113.10",
      "ttl": 3600,
      "priority": 0,
      "proxied": false,
      "comment": "Web servers",
      "tags": [
        "web"
      ],
      "source": "file"
    }
  ],
  "skipped": [
    {
      "line": 0,
      "text": "example",
      "reason": "Point www at the new origin"
    }
  ],
  "skipped_total": 128,
  "truncated": false
}

Ver las respuestas DNS del borde

GET /v1/orgs/{org}/zones/{zone}/dns/answers

En una zona delegada, devuelve las direcciones que publica el DNS de OpenWAF para cada nombre con proxy (las del borde) y si la respuesta publicada está al día (in_sync; si no, se corrige sola).

Rol necesario: readonly o superior.

Parámetros

NombreEnTipoObligatorioDescripción
orgrutastring (uuid)SíId de la organización. Cada ruta comprueba que es la del token (si no, 404).
zonerutastring (uuid)SíId de la zona (consulta Listar zonas).

Respuesta

CampoTipoDescripción
ipv4array de string
ipv6array de string
namesarray de object
names[].namestringNombre.
names[].in_syncboolean
names[].rrsetsarray de object

Errores

EstadoDescripción
404No existe o el token no lo ve (not_found).
409conflict: la zona es externa (su DNS lo sirve otro proveedor).
503El servicio DNS no está disponible ahora.

Ejemplo

curl "https://dash.openwaf.dev/v1/orgs/$OPENWAF_ORG/zones/6f1d2c3b-8a4e-4b7d-9c21-5e3f7a8b9c0d/dns/answers" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
200
{
  "ipv4": [
    "example"
  ],
  "ipv6": [
    "example"
  ],
  "names": [
    {
      "name": "example.com",
      "in_sync": false,
      "rrsets": [
        {}
      ]
    }
  ]
}

Última actualización:

↑↓ para moverte↵ para abriresc para cerrar