# Referencia de la API > Gestiona zonas, registros DNS, ajustes de borde, reglas, analítica, agentes IA y egress con la API REST de OpenWAF. La API de OpenWAF es una API REST con JSON sobre HTTPS. Gestiona todo lo que hace el panel: zonas y registros DNS, ajustes de borde y reglas, certificados y caché, analítica, agentes IA, egress, miembros y tokens de API. Los [SDK](https://developers.openwaf.dev/es/sdk/), la [CLI](https://developers.openwaf.dev/es/cli/) y el [servidor MCP](https://developers.openwaf.dev/es/mcp/) usan esta misma API. > **Nota** > > Esta referencia se genera a partir de la especificación OpenAPI de la API (120 operaciones). Los SDK de TypeScript y Python se generan de la misma especificación, así que sus métodos se llaman como los identificadores de operación de esta referencia. ## URL base ```text https://dash.openwaf.dev/v1 ``` Los recursos de la organización están bajo `/v1/orgs/{org}` y los de una zona bajo `/v1/orgs/{org}/zones/{zone}`. `{org}` es el id de tu organización y `{zone}` el de una zona, ambos UUID. `GET /v1/orgs` devuelve la organización del token, y [Listar zonas](https://developers.openwaf.dev/es/api/zones/#list-zones) devuelve los ids de las zonas. ## Autenticación Cada petición lleva un token de API en la cabecera `Authorization`: ```http GET /v1/orgs HTTP/1.1 Host: dash.openwaf.dev Authorization: Bearer owf_… ``` Los tokens se crean en el panel (**Tokens de API**) o con [Crear un token](https://developers.openwaf.dev/es/api/tokens/#create-token). Un token actúa con un [rol](https://developers.openwaf.dev/es/api/authentication/#roles) y se puede limitar a una zona o a un cliente. Una petición sobre una organización que no es la del token responde `404`, igual que un recurso que no existe. Consulta [Autenticación](https://developers.openwaf.dev/es/api/authentication/). ## Peticiones y respuestas - Los cuerpos de las peticiones son JSON (`Content-Type: application/json`) salvo que la operación diga otra cosa, de hasta 1 MiB. Los campos desconocidos se rechazan con `400 bad_request`. - Las fechas van en RFC 3339 y UTC, y los ids son UUID. - Las listas responden `{"items": […]}`. Las largas se paginan con `limit` y un cursor (`cursor`, `before`) que describe cada operación. - Las respuestas `204 No Content` no llevan cuerpo. ## Cambios de configuración La configuración de una zona (registros, ajustes de borde, reglas, su cliente) está versionada: cada cambio crea una versión con su autor y su motivo, visible en [Versiones de configuración](https://developers.openwaf.dev/es/api/versions/) y en la [auditoría](https://developers.openwaf.dev/es/api/audit/). Las escrituras que cambian la configuración admiten tres controles: | Control | Dónde | Efecto | |---|---|---| | `X-Change-Reason` | Cabecera | Motivo del cambio, de 1 a 500 caracteres, que queda en el historial y en la auditoría. Lo exigen la mayoría de las escrituras: sin él responden `422 reason_required`. | | `dry_run=1` | Consulta | Simula el cambio: responde `200` con el plan ([Applied](https://developers.openwaf.dev/es/api/schemas/#applied)), las diferencias y la versión que crearía. No guarda nada. | | `If-Match` | Cabecera | Versión actual esperada, p. ej. `"12"`. Si la zona ha cambiado desde entonces, la escritura responde `412 version_conflict` con `current_version`. | Las escrituras correctas devuelven la nueva versión en la cabecera `X-Config-Version` y en `ETag` (entre comillas, lista para `If-Match`). La forma segura de cambiar una zona, los mismos dos pasos que exige el servidor MCP: 1. Envía la escritura con `dry_run=1` y revisa el plan; la versión actual está en `from_version` (o en el `ETag` de la zona). 2. Envía la misma escritura sin `dry_run`, con `If-Match: ""` y un `X-Change-Reason`. Si alguien ha cambiado la zona entretanto recibirás `412 version_conflict`: vuelve a simular. ## Errores Los errores responden un estado HTTP y un cuerpo JSON con un `code` estable: ```json {"error": {"code": "invalid", "message": "ttl must be between 60 and 86400", "field": "ttl"}} ``` Todos los códigos están en [Errores](https://developers.openwaf.dev/es/api/errors/). ## Límites de peticiones Algunas operaciones tienen sus propios límites y, al superarlos, responden `429` con una cabecera `Retry-After` (en segundos): | Operación | Límite | |---|---| | [Purgar la caché](https://developers.openwaf.dev/es/api/cache/#purge-cache) | Por organización: 10 purgas por minuto con ráfagas de 30 (todo, nombres, prefijos, etiquetas) y 500 URL por minuto. | | [Escanear la preparación para agentes](https://developers.openwaf.dev/es/api/agent-readiness/#scan-agent-readiness) | Una vez por nombre y minuto. | | [Stream de eventos de seguridad](https://developers.openwaf.dev/es/api/security-events/#stream-events) y [stream de eventos de egress](https://developers.openwaf.dev/es/api/egress/#stream-egress-events) | 10 streams abiertos por organización. | ## Versiones de la API Todas las rutas están bajo `/v1`. Con el tiempo, las respuestas pueden ganar campos nuevos y los enumerados valores nuevos: los clientes deben ignorar los campos que no conozcan. Los cambios de la API se anuncian en el [registro de cambios](https://developers.openwaf.dev/es/changelog/). ## SDK, CLI y MCP - [SDK](https://developers.openwaf.dev/es/sdk/): clientes de TypeScript y Python generados de esta API, un fichero cada uno. - [CLI](https://developers.openwaf.dev/es/cli/): `openwaf-cloud ctl`, la API desde el terminal y desde scripts. - [Servidor MCP](https://developers.openwaf.dev/es/mcp/): la API como herramientas para asistentes de IA, en `https://mcp.openwaf.dev/mcp`. La propia API sirve los ficheros de los SDK sin autenticación: `https://dash.openwaf.dev/v1/sdk/openwaf.ts` y `https://dash.openwaf.dev/v1/sdk/openwaf.py`. ## Referencia - [Organizaciones](https://developers.openwaf.dev/es/api/organizations/): Consulta y renombra tu organización, la cuenta a la que pertenecen las zonas, los miembros y los tokens. - [Miembros e invitaciones](https://developers.openwaf.dev/es/api/members/): Lista, añade y quita a las personas de tu organización, cambia sus roles y gestiona las invitaciones. - [Tokens de API](https://developers.openwaf.dev/es/api/tokens/): Crea, lista y revoca los tokens owf_ que autentican las peticiones a la API, la CLI y el servidor MCP. - [Clientes](https://developers.openwaf.dev/es/api/clients/): Agrupa las zonas por los clientes finales de una agencia y limita miembros y tokens a las zonas de un cliente. - [Marca blanca](https://developers.openwaf.dev/es/api/white-label/): Pon tu nombre, color y logotipo en el panel, sírvelo en tu propio dominio y usa tus propios servidores de nombres. - [Auditoría](https://developers.openwaf.dev/es/api/audit/): Lee la auditoría de tu organización, cada cambio hecho desde la API, el panel, la CLI o MCP. - [Zonas](https://developers.openwaf.dev/es/api/zones/): Añade, lista, comprueba y borra zonas (dominios), en modo DNS delegado o externo, y fusiona una zona en su padre. - [Versiones de configuración](https://developers.openwaf.dev/es/api/versions/): Recorre el historial de versiones de una zona, compara dos versiones, vuelve a una anterior y sigue su propagación al borde. - [Registros DNS](https://developers.openwaf.dev/es/api/dns-records/): Lista, crea, modifica y borra los registros DNS de una zona, en bloque o en un lote, e importa los registros existentes. - [DNS del correo](https://developers.openwaf.dev/es/api/email/): Planifica los registros MX, SPF, DKIM y DMARC de tus proveedores de correo y comprueba los registros de correo de una zona. - [Ajustes de borde](https://developers.openwaf.dev/es/api/edge-settings/): Consulta y cambia los ajustes de borde de una zona (WAF, origen, TLS, caché, agentes IA…) y la configuración efectiva de un nombre. - [Reglas](https://developers.openwaf.dev/es/api/rules/): Añade, lista y borra las reglas de borde de una zona, reglas de IP y país, excepciones del WAF y límites de peticiones. - [Caché](https://developers.openwaf.dev/es/api/cache/): Purga lo que el borde guardó en caché de una zona, todo o por URL, prefijo, nombre o etiqueta, y sigue las purgas recientes. - [Certificados del borde](https://developers.openwaf.dev/es/api/certificates/): Lista los certificados TLS de una zona y el estado del certificado de cada sitio con proxy. - [TLS al origen y Origin CA](https://developers.openwaf.dev/es/api/origin-tls/): Emite y revoca certificados de origen de la OpenWAF Origin CA, comprueba el TLS al origen y descarga las CA. - [Eventos de seguridad](https://developers.openwaf.dev/es/api/security-events/): Consulta los eventos de seguridad de una zona, con filtros, resúmenes, histogramas y un stream en directo (Server-Sent Events). - [Uso](https://developers.openwaf.dev/es/api/usage/): Contadores diarios de tráfico de una zona en el borde, peticiones, peticiones bloqueadas, bytes y consultas DNS. - [Rendimiento real (RUM)](https://developers.openwaf.dev/es/api/rum/): Core Web Vitals medidos en los navegadores de tus visitantes, LCP, INP, CLS, FCP y TTFB, por página, país, dispositivo y más. - [Agentes IA](https://developers.openwaf.dev/es/api/ai-agents/): Cómo usan una zona los rastreadores y agentes IA, por categoría, bot y operador, más trampas, señales, MCP Shield y el catálogo. - [Preparación para agentes](https://developers.openwaf.dev/es/api/agent-readiness/): Escanea lo preparado que está un nombre de la zona para agentes IA, reglas de robots.txt, sitemap, llms.txt, markdown y datos estructurados. - [Egress](https://developers.openwaf.dev/es/api/egress/): Gestiona OpenWAF Egress, la pasarela entre tus agentes IA y sus proveedores, con destinos, credenciales, agentes y eventos. - [Esquemas](https://developers.openwaf.dev/es/api/schemas/): todos los objetos que devuelve o acepta la API. ## Sesión del panel La entrada (`/v1/auth/…`), la aceptación de invitaciones y el borrado de la cuenta sirven al panel con una cookie de sesión y no forman parte de la API con tokens. Con la cookie de sesión, el panel también llama a las rutas de esta referencia; sus escrituras exigen entonces la cabecera `X-CSRF-Token`. Las integraciones usan siempre un token de API.