{
  "openapi": "3.1.0",
  "info": {
    "title": "SubnetKit API",
    "version": "1.1.0",
    "description": "Static, keyless JSON reference data for IPv4 CIDR prefixes, TCP and UDP port numbers, and reserved address ranges. Served as files from a CDN, so there is no authentication and no rate limit.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "url": "https://subnetkit.dev/contact"
    }
  },
  "servers": [
    {
      "url": "https://subnetkit.dev"
    }
  ],
  "paths": {
    "/api/index.json": {
      "get": {
        "summary": "API index: version, endpoint list and record counts",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "The index document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Index"
                }
              }
            }
          }
        }
      }
    },
    "/api/cidr.json": {
      "get": {
        "summary": "Every IPv4 prefix from /0 to /32",
        "operationId": "getAllPrefixes",
        "responses": {
          "200": {
            "description": "All 33 prefixes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CidrCollection"
                }
              }
            }
          }
        }
      }
    },
    "/api/cidr/{prefix}.json": {
      "get": {
        "summary": "One IPv4 prefix",
        "operationId": "getPrefix",
        "parameters": [
          {
            "name": "prefix",
            "in": "path",
            "required": true,
            "description": "Prefix length, 0 to 32",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 32
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The prefix record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cidr"
                }
              }
            }
          },
          "404": {
            "description": "No such prefix"
          }
        }
      }
    },
    "/api/ports.json": {
      "get": {
        "summary": "The curated TCP and UDP port list",
        "operationId": "getPorts",
        "responses": {
          "200": {
            "description": "All ports",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortCollection"
                }
              }
            }
          }
        }
      }
    },
    "/api/reserved.json": {
      "get": {
        "summary": "Reserved and special-purpose IPv4 and IPv6 blocks, each with its RFC",
        "operationId": "getReserved",
        "responses": {
          "200": {
            "description": "Reserved blocks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReservedCollection"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "License": {
        "type": "object",
        "required": [
          "name",
          "url",
          "attribution"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Licence name"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "attribution": {
            "type": "string",
            "description": "How to attribute the data"
          }
        }
      },
      "Cidr": {
        "type": "object",
        "required": [
          "prefix",
          "mask",
          "wildcard",
          "totalHosts",
          "usableHosts",
          "role"
        ],
        "properties": {
          "updated": {
            "type": "string",
            "format": "date",
            "description": "Date the record last changed"
          },
          "prefix": {
            "type": "integer",
            "minimum": 0,
            "maximum": 32,
            "description": "Prefix length in bits"
          },
          "mask": {
            "type": "string",
            "description": "Subnet mask in dotted-quad form"
          },
          "wildcard": {
            "type": "string",
            "description": "Wildcard mask, the bitwise complement of the subnet mask"
          },
          "totalHosts": {
            "type": "integer",
            "description": "Total addresses in the block, 2^(32-prefix)"
          },
          "usableHosts": {
            "type": "integer",
            "description": "Assignable addresses. Total minus two for network and broadcast, except /31 (2, RFC 3021) and /32 (1)."
          },
          "role": {
            "type": "string",
            "description": "Plain-English label for what the prefix is typically used for"
          }
        }
      },
      "CidrCollection": {
        "type": "object",
        "required": [
          "updated",
          "count",
          "prefixes"
        ],
        "properties": {
          "updated": {
            "type": "string",
            "format": "date"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "count": {
            "type": "integer"
          },
          "prefixes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Cidr"
            }
          }
        }
      },
      "Port": {
        "type": "object",
        "required": [
          "port",
          "name",
          "protocol",
          "service",
          "category",
          "description",
          "secure",
          "official",
          "common"
        ],
        "properties": {
          "port": {
            "type": "integer",
            "minimum": 0,
            "maximum": 65535
          },
          "name": {
            "type": "string",
            "description": "Short service name, for example SSH"
          },
          "protocol": {
            "type": "string",
            "enum": [
              "TCP",
              "UDP",
              "TCP/UDP"
            ],
            "description": "Transport in practice"
          },
          "service": {
            "type": "string",
            "description": "Longer service label"
          },
          "category": {
            "type": "string",
            "description": "Grouping used by the site hubs"
          },
          "description": {
            "type": "string",
            "description": "One or two sentences on what the port is for"
          },
          "secure": {
            "type": "boolean",
            "description": "True when traffic is encrypted by default"
          },
          "official": {
            "type": "boolean",
            "description": "True when the assignment is in the IANA registry"
          },
          "common": {
            "type": "boolean",
            "description": "True when the port is on the hand-picked list of ports people actually look up"
          }
        }
      },
      "PortCollection": {
        "type": "object",
        "required": [
          "dataUpdated",
          "sourceVerified",
          "count",
          "ports"
        ],
        "properties": {
          "updated": {
            "type": "string",
            "format": "date",
            "description": "Alias of dataUpdated, kept for older consumers"
          },
          "dataUpdated": {
            "type": "string",
            "format": "date",
            "description": "Date an entry in the list last changed"
          },
          "sourceVerified": {
            "type": "string",
            "format": "date",
            "description": "Date the list was last checked against the IANA registry"
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "count": {
            "type": "integer"
          },
          "ports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Port"
            }
          }
        }
      },
      "ReservedBlock": {
        "type": "object",
        "required": [
          "cidr",
          "name",
          "note",
          "rfc",
          "rfcUrl",
          "globallyRoutable"
        ],
        "properties": {
          "cidr": {
            "type": "string",
            "description": "The block in CIDR notation"
          },
          "name": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "rfc": {
            "type": "string",
            "description": "The document that defines the block, for example RFC 1918"
          },
          "rfcUrl": {
            "type": "string",
            "format": "uri"
          },
          "globallyRoutable": {
            "type": "boolean"
          }
        }
      },
      "ReservedCollection": {
        "type": "object",
        "required": [
          "updated",
          "ipv4",
          "ipv6"
        ],
        "properties": {
          "updated": {
            "type": "string",
            "format": "date"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "ipv4": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "blocks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReservedBlock"
                }
              }
            }
          },
          "ipv6": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "blocks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReservedBlock"
                }
              }
            }
          }
        }
      },
      "Index": {
        "type": "object",
        "required": [
          "name",
          "version",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "updated": {
            "type": "string",
            "format": "date"
          },
          "license": {
            "$ref": "#/components/schemas/License"
          },
          "endpoints": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "changelog": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}