{
  "openapi": "3.0.3",
  "info": {
    "title": "AllZonefiles.io API",
    "version": "1.0.0",
    "description": "Access and download zonefiles and domain lists for all domain zones.\n\n**Authentication:** send your API token in the `Authorization: Bearer <token>` header. The token is on the [API Token](https://allzonefiles.io/userapp/api-token) page of your account.\n\n**Access:** list endpoints are available to every registered user with an API token. Downloading the latest files requires the Basic or Pro plan, downloading historical (dated) files requires the Pro plan and counts toward monthly download limits (see `GET /limits/historical`).\n\n**Dates** use the `YYYY-MM-DD` format. Lists of files are sorted by date, most recent first.\n\n**Errors** are returned as JSON `{\"errorMessage\": \"...\"}`, except for rate limiting (`429`), which returns `{\"error\": \"...\"}`. When the requested file is not available (for example, no file for that zone and date), download endpoints respond with `500`.",
    "termsOfService": "https://allzonefiles.io/tos",
    "contact": {
      "name": "AllZonefiles.io",
      "url": "https://allzonefiles.io/contact"
    }
  },
  "externalDocs": {
    "description": "API documentation",
    "url": "https://allzonefiles.io/apidocs"
  },
  "servers": [
    {
      "url": "https://allzonefiles.io/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Zonefiles",
      "description": "Zonefiles for gTLD and ccTLD zones, as gzipped lists of domain names (one domain name per line)."
    },
    {
      "name": "CZDS-format zonefiles",
      "description": "Zonefiles for gTLD zones in the original ICANN CZDS format: the complete zonefile with its DNS records."
    },
    {
      "name": "ZIP archives",
      "description": ".ZIP archives with all zonefiles."
    },
    {
      "name": "New domain lists",
      "description": "Daily lists of newly registered domains across all zones."
    },
    {
      "name": "Expired domain lists",
      "description": "Daily lists of expired domains across all zones."
    },
    {
      "name": "Download limits",
      "description": "Monthly limits for downloading historical files."
    }
  ],
  "paths": {
    "/zones": {
      "get": {
        "tags": [
          "Zonefiles"
        ],
        "operationId": "listZones",
        "summary": "List all zones with latest zonefile data",
        "description": "All available gTLD and ccTLD zones with the date, number of domains and file size of the latest zonefile, sorted by zone name.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZonesList"
                },
                "example": {
                  "zones": [
                    {
                      "name": "com",
                      "type": "gTLD",
                      "latest_update_date": "2026-06-05",
                      "filesize_bytes": 616970673,
                      "domains": 155447708
                    },
                    {
                      "name": "net",
                      "type": "gTLD",
                      "latest_update_date": "2026-06-05",
                      "filesize_bytes": 49463253,
                      "domains": 12332251
                    },
                    {
                      "name": "uk",
                      "type": "ccTLD",
                      "latest_update_date": "2026-06-05",
                      "filesize_bytes": 40290566,
                      "domains": 9750218
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/zones/{zone}": {
      "get": {
        "tags": [
          "Zonefiles"
        ],
        "operationId": "listZonefiles",
        "summary": "List all zonefiles for a zone",
        "description": "All available zonefiles for the zone, most recent first.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZonefilesList"
                },
                "example": {
                  "zone": "dev",
                  "type": "gTLD",
                  "zonefiles": [
                    {
                      "date": "2026-06-05",
                      "domains": 677062,
                      "filesize_bytes": 2440862
                    },
                    {
                      "date": "2026-06-04",
                      "domains": 676378,
                      "filesize_bytes": 2438361
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Unknown zone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errorMessage": "Zone does not exist: xyz"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          }
        ]
      }
    },
    "/zones/{zone}/dl": {
      "get": {
        "tags": [
          "Zonefiles"
        ],
        "operationId": "downloadLatestZonefile",
        "summary": "Download latest zonefile for a zone",
        "description": "Latest zonefile for the zone: a gzipped text file with one domain name per line, named `{zone}.{date}.txt.gz`.\n\n**Access:** Basic or Pro plan.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=dev.2026-06-05.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=dev.2026-06-05.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          }
        ]
      }
    },
    "/zones/{zone}/dl/{date}": {
      "get": {
        "tags": [
          "Zonefiles"
        ],
        "operationId": "downloadHistoricZonefile",
        "summary": "Download historic zonefile for a zone and date",
        "description": "Zonefile for the zone for the given date: a gzipped text file with one domain name per line, named `{zone}.{date}.txt.gz`. Use `GET /zones/{zone}` to find the available dates.\n\n**Access:** Pro plan. Counts toward the monthly historical download limits, see `GET /limits/historical`.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=dev.2026-05-11.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=dev.2026-05-11.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadDate"
          },
          "401": {
            "$ref": "#/components/responses/HistoricDownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          },
          {
            "$ref": "#/components/parameters/Date"
          }
        ]
      }
    },
    "/czds/zones": {
      "get": {
        "tags": [
          "CZDS-format zonefiles"
        ],
        "operationId": "listCzdsZones",
        "summary": "List all zones with latest CZDS-format zonefile data",
        "description": "All gTLD zones with CZDS-format zonefiles, with the date, number of domains and file size of the latest zonefile, sorted by zone name.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZonesList"
                },
                "example": {
                  "zones": [
                    {
                      "name": "com",
                      "type": "gTLD",
                      "latest_update_date": "2026-06-05",
                      "filesize_bytes": 4987563120,
                      "domains": 155447708
                    },
                    {
                      "name": "dev",
                      "type": "gTLD",
                      "latest_update_date": "2026-06-05",
                      "filesize_bytes": 21874412,
                      "domains": 677062
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/czds/zones/{zone}": {
      "get": {
        "tags": [
          "CZDS-format zonefiles"
        ],
        "operationId": "listCzdsZonefiles",
        "summary": "List all CZDS-format zonefiles for a zone",
        "description": "All available CZDS-format zonefiles for the zone, most recent first.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZonefilesList"
                },
                "example": {
                  "zone": "dev",
                  "type": "gTLD",
                  "zonefiles": [
                    {
                      "date": "2026-06-05",
                      "domains": 677062,
                      "filesize_bytes": 21874412
                    },
                    {
                      "date": "2026-06-04",
                      "domains": 676378,
                      "filesize_bytes": 21851037
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Unknown zone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errorMessage": "CZDS zone does not exist: xyz"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          }
        ]
      }
    },
    "/czds/zones/{zone}/dl": {
      "get": {
        "tags": [
          "CZDS-format zonefiles"
        ],
        "operationId": "downloadLatestCzdsZonefile",
        "summary": "Download latest CZDS-format zonefile for a zone",
        "description": "Latest zonefile for the zone in the original ICANN CZDS format (the complete zonefile with its DNS records), gzipped, named `{zone}.{date}.full_zonefile.txt.gz`.\n\n**Access:** Basic or Pro plan.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=dev.2026-06-05.full_zonefile.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=dev.2026-06-05.full_zonefile.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          }
        ]
      }
    },
    "/czds/zones/{zone}/dl/{date}": {
      "get": {
        "tags": [
          "CZDS-format zonefiles"
        ],
        "operationId": "downloadHistoricCzdsZonefile",
        "summary": "Download historic CZDS-format zonefile for a zone and date",
        "description": "Zonefile for the zone for the given date in the original ICANN CZDS format, gzipped, named `{zone}.{date}.full_zonefile.txt.gz`. Use `GET /czds/zones/{zone}` to find the available dates.\n\n**Access:** Pro plan. Counts toward the monthly historical download limits, see `GET /limits/historical`.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=dev.2026-05-11.full_zonefile.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=dev.2026-05-11.full_zonefile.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadDate"
          },
          "401": {
            "$ref": "#/components/responses/HistoricDownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Zone"
          },
          {
            "$ref": "#/components/parameters/Date"
          }
        ]
      }
    },
    "/all": {
      "get": {
        "tags": [
          "ZIP archives"
        ],
        "operationId": "listAllZonefilesArchives",
        "summary": "List available .ZIP archives with all zonefiles",
        "description": "All available .ZIP archives with all zonefiles, most recent first.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainListsList"
                },
                "example": {
                  "lists": [
                    {
                      "date": "2026-06-04",
                      "domains": 367042384,
                      "filesize_bytes": 1482563882
                    },
                    {
                      "date": "2026-06-03",
                      "domains": 366897871,
                      "filesize_bytes": 1481974088
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/all/dl": {
      "get": {
        "tags": [
          "ZIP archives"
        ],
        "operationId": "downloadLatestAllZonefilesArchive",
        "summary": "Download latest .ZIP archive with all zonefiles",
        "description": "Latest .ZIP archive with all zonefiles, named `all_zonefiles.{date}.zip`.\n\n**Access:** Basic or Pro plan.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=all_zonefiles.2026-06-04.zip`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=all_zonefiles.2026-06-04.zip"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        }
      }
    },
    "/all/dl/{date}": {
      "get": {
        "tags": [
          "ZIP archives"
        ],
        "operationId": "downloadHistoricAllZonefilesArchive",
        "summary": "Download historic .ZIP archive with all zonefiles for a date",
        "description": ".ZIP archive with all zonefiles for the given date, named `all_zonefiles.{date}.zip`. Use `GET /all` to find the available dates.\n\n**Access:** Pro plan. Counts toward the monthly historical download limits, see `GET /limits/historical`.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=all_zonefiles.2026-05-11.zip`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=all_zonefiles.2026-05-11.zip"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadDate"
          },
          "401": {
            "$ref": "#/components/responses/HistoricDownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          }
        ]
      }
    },
    "/new": {
      "get": {
        "tags": [
          "New domain lists"
        ],
        "operationId": "listNewDomainLists",
        "summary": "List available new domain lists",
        "description": "Daily lists of newly registered domains across all zones, most recent first.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainListsList"
                },
                "example": {
                  "lists": [
                    {
                      "date": "2026-06-04",
                      "domains": 281130,
                      "filesize_bytes": 1667401
                    },
                    {
                      "date": "2026-06-03",
                      "domains": 188591,
                      "filesize_bytes": 1159870
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/new/dl": {
      "get": {
        "tags": [
          "New domain lists"
        ],
        "operationId": "downloadLatestNewDomainList",
        "summary": "Download latest new domain list",
        "description": "Latest list of new domains: a gzipped text file with one domain name per line, named `new.{date}.txt.gz`.\n\n**Access:** Basic or Pro plan.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=new.2026-06-04.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=new.2026-06-04.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        }
      }
    },
    "/new/dl/{date}": {
      "get": {
        "tags": [
          "New domain lists"
        ],
        "operationId": "downloadHistoricNewDomainList",
        "summary": "Download new domain list for a date",
        "description": "List of new domains for the given date: a gzipped text file with one domain name per line, named `new.{date}.txt.gz`. Use `GET /new` to find the available dates.\n\n**Access:** Pro plan. Counts toward the monthly historical download limits, see `GET /limits/historical`.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=new.2026-05-11.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=new.2026-05-11.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadDate"
          },
          "401": {
            "$ref": "#/components/responses/HistoricDownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          }
        ]
      }
    },
    "/expired": {
      "get": {
        "tags": [
          "Expired domain lists"
        ],
        "operationId": "listExpiredDomainLists",
        "summary": "List available expired domain lists",
        "description": "Daily lists of expired domains across all zones, most recent first.\n\n**Access:** any registered user with an API token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainListsList"
                },
                "example": {
                  "lists": [
                    {
                      "date": "2026-06-04",
                      "domains": 281130,
                      "filesize_bytes": 1667401
                    },
                    {
                      "date": "2026-06-03",
                      "domains": 188591,
                      "filesize_bytes": 1159870
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/expired/dl": {
      "get": {
        "tags": [
          "Expired domain lists"
        ],
        "operationId": "downloadLatestExpiredDomainList",
        "summary": "Download latest expired domain list",
        "description": "Latest list of expired domains: a gzipped text file with one domain name per line, named `expired.{date}.txt.gz`.\n\n**Access:** Basic or Pro plan.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=expired.2026-06-04.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=expired.2026-06-04.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/DownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        }
      }
    },
    "/expired/dl/{date}": {
      "get": {
        "tags": [
          "Expired domain lists"
        ],
        "operationId": "downloadHistoricExpiredDomainList",
        "summary": "Download expired domain list for a date",
        "description": "List of expired domains for the given date: a gzipped text file with one domain name per line, named `expired.{date}.txt.gz`. Use `GET /expired` to find the available dates.\n\n**Access:** Pro plan. Counts toward the monthly historical download limits, see `GET /limits/historical`.",
        "responses": {
          "200": {
            "description": "The requested file.",
            "headers": {
              "Content-Disposition": {
                "description": "Suggested file name, e.g. `attachment; filename=expired.2026-05-11.txt.gz`.",
                "schema": {
                  "type": "string"
                },
                "example": "attachment; filename=expired.2026-05-11.txt.gz"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadDate"
          },
          "401": {
            "$ref": "#/components/responses/HistoricDownloadUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DownloadFailed"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          }
        ]
      }
    },
    "/limits/historical": {
      "get": {
        "tags": [
          "Download limits"
        ],
        "operationId": "getHistoricalFilesDownloadLimits",
        "summary": "Get historical files download limits",
        "description": "Limits for the current billing period, how much has been used and how much remains. All historical (dated) downloads count toward the limits - zonefiles, CZDS-format zonefiles, new/expired domain lists and .ZIP archives, via both the website and the API. Downloads of the latest files are not limited. A billing period is one month long and starts on the subscription date.\n\n**Access:** Pro plan.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoricalFilesDownloadLimits"
                },
                "example": {
                  "period_start_utc": "2026-09-15T14:32:07Z",
                  "period_end_utc": "2026-10-15T14:32:07Z",
                  "max_files": 500,
                  "max_data_mb": 256000,
                  "downloaded_files": 123,
                  "downloaded_data_mb": 212000,
                  "remaining_files": 377,
                  "remaining_data_mb": 44000,
                  "quota_exceeded": false
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token, or the plan does not include historical files.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "noHistoricalAccess": {
                    "value": {
                      "errorMessage": "No subscription that allows to download historical files"
                    }
                  },
                  "invalidToken": {
                    "value": {
                      "errorMessage": "Invalid API Token (unknown token)"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Download limits are not enabled, so historical downloads are not limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "errorMessage": "Historical files download limits are not enabled"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token, for example `allzfio_5c1572d016b846ce99ce7a177922ff21`."
      }
    },
    "parameters": {
      "Zone": {
        "name": "zone",
        "in": "path",
        "required": true,
        "description": "Zone name without the leading dot.",
        "schema": {
          "type": "string"
        },
        "example": "dev"
      },
      "Date": {
        "name": "date",
        "in": "path",
        "required": true,
        "description": "Date in `YYYY-MM-DD` format.",
        "schema": {
          "type": "string",
          "format": "date"
        },
        "example": "2026-05-11"
      }
    },
    "headers": {
      "ContentLength": {
        "description": "File size in bytes.",
        "schema": {
          "type": "integer",
          "format": "int64"
        }
      }
    },
    "schemas": {
      "ZoneType": {
        "type": "string",
        "enum": [
          "gTLD",
          "ccTLD"
        ]
      },
      "ZoneInfo": {
        "type": "object",
        "required": [
          "name",
          "type",
          "latest_update_date",
          "filesize_bytes",
          "domains"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Zone name without the leading dot.",
            "example": "com"
          },
          "type": {
            "$ref": "#/components/schemas/ZoneType"
          },
          "latest_update_date": {
            "type": "string",
            "format": "date",
            "description": "Date of the latest file."
          },
          "filesize_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "Size of the latest file in bytes."
          },
          "domains": {
            "type": "integer",
            "format": "int64",
            "description": "Number of domains in the latest file."
          }
        }
      },
      "ZonesList": {
        "type": "object",
        "required": [
          "zones"
        ],
        "properties": {
          "zones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ZoneInfo"
            }
          }
        }
      },
      "Zonefile": {
        "type": "object",
        "required": [
          "date",
          "domains",
          "filesize_bytes"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "domains": {
            "type": "integer",
            "format": "int64",
            "description": "Number of domains in the file."
          },
          "filesize_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "File size in bytes."
          }
        }
      },
      "ZonefilesList": {
        "type": "object",
        "required": [
          "zone",
          "type",
          "zonefiles"
        ],
        "properties": {
          "zone": {
            "type": "string",
            "description": "Zone name without the leading dot."
          },
          "type": {
            "$ref": "#/components/schemas/ZoneType"
          },
          "zonefiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Zonefile"
            },
            "description": "Most recent first."
          }
        }
      },
      "DomainList": {
        "type": "object",
        "required": [
          "date",
          "domains",
          "filesize_bytes"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "domains": {
            "type": "integer",
            "format": "int64",
            "description": "Number of domains in the file."
          },
          "filesize_bytes": {
            "type": "integer",
            "format": "int64",
            "description": "File size in bytes."
          }
        }
      },
      "DomainListsList": {
        "type": "object",
        "required": [
          "lists"
        ],
        "properties": {
          "lists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DomainList"
            },
            "description": "Most recent first."
          }
        }
      },
      "HistoricalFilesDownloadLimits": {
        "type": "object",
        "required": [
          "period_start_utc",
          "period_end_utc",
          "max_files",
          "max_data_mb",
          "downloaded_files",
          "downloaded_data_mb",
          "remaining_files",
          "remaining_data_mb",
          "quota_exceeded"
        ],
        "properties": {
          "period_start_utc": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the current billing period (UTC)."
          },
          "period_end_utc": {
            "type": "string",
            "format": "date-time",
            "description": "End of the current billing period (UTC). If the subscription ends earlier, this is the subscription end time."
          },
          "max_files": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum number of historical files per billing period."
          },
          "max_data_mb": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum amount of historical data per billing period, in MB (1 GB = 1024 MB)."
          },
          "downloaded_files": {
            "type": "integer",
            "format": "int64",
            "description": "Historical files downloaded in the current billing period."
          },
          "downloaded_data_mb": {
            "type": "integer",
            "format": "int64",
            "description": "Historical data downloaded in the current billing period, in MB."
          },
          "remaining_files": {
            "type": "integer",
            "format": "int64",
            "description": "Historical files left until the end of the billing period."
          },
          "remaining_data_mb": {
            "type": "integer",
            "format": "int64",
            "description": "Historical data left until the end of the billing period, in MB."
          },
          "quota_exceeded": {
            "type": "boolean",
            "description": "`true` once either limit is reached. Historical downloads are then rejected until the next billing period starts."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "errorMessage": {
            "type": "string"
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "noToken": {
                "value": {
                  "errorMessage": "No API Token found"
                }
              },
              "noBearerPrefix": {
                "value": {
                  "errorMessage": "Authorization header must start with 'Bearer ' prefix."
                }
              },
              "unknownToken": {
                "value": {
                  "errorMessage": "Invalid API Token (unknown token)"
                }
              },
              "inactiveUser": {
                "value": {
                  "errorMessage": "Invalid API Token (user is not in active state)"
                }
              }
            }
          }
        }
      },
      "DownloadUnauthorized": {
        "description": "Missing or invalid API token, or the plan does not include this file.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "noPermission": {
                "value": {
                  "errorMessage": "no permissions to download file"
                }
              },
              "noToken": {
                "value": {
                  "errorMessage": "No API Token found"
                }
              },
              "noBearerPrefix": {
                "value": {
                  "errorMessage": "Authorization header must start with 'Bearer ' prefix."
                }
              },
              "unknownToken": {
                "value": {
                  "errorMessage": "Invalid API Token (unknown token)"
                }
              },
              "inactiveUser": {
                "value": {
                  "errorMessage": "Invalid API Token (user is not in active state)"
                }
              }
            }
          }
        }
      },
      "HistoricDownloadUnauthorized": {
        "description": "Missing or invalid API token, the plan does not include historical files, or the monthly download limit has been reached.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "quotaExceeded": {
                "value": {
                  "errorMessage": "Download quota exceeded"
                }
              },
              "noPermission": {
                "value": {
                  "errorMessage": "No permissions to download file"
                }
              },
              "noToken": {
                "value": {
                  "errorMessage": "No API Token found"
                }
              },
              "noBearerPrefix": {
                "value": {
                  "errorMessage": "Authorization header must start with 'Bearer ' prefix."
                }
              },
              "unknownToken": {
                "value": {
                  "errorMessage": "Invalid API Token (unknown token)"
                }
              },
              "inactiveUser": {
                "value": {
                  "errorMessage": "Invalid API Token (user is not in active state)"
                }
              }
            }
          }
        }
      },
      "BadDate": {
        "description": "The date is not in `YYYY-MM-DD` format.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "errorMessage": "Bad date format: '2026-5-11'. Should be in format 'YYYY-mm-dd', for instance: '2025-07-24'."
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded. Wait a few seconds and retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimitError"
            },
            "example": {
              "error": "Rate limit exceeded for this resource."
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "DownloadFailed": {
        "description": "Internal error, or the requested file is not available (for example, no file for that zone and date).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "errorMessage": "Error downloading zonefile"
            }
          }
        }
      }
    }
  }
}