{
  "openapi": "3.1.0",
  "info": {
    "title": "cf-ip-info",
    "description": "Returns IP geolocation and threat intelligence data.",
    "version": "0.2.2"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/all": {
      "get": {
        "summary": "All IP information",
        "description": "Returns all aggregated data for the IP: geolocation, AbuseIPDB report, and VirusTotal report.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "All IP data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country": {
                      "type": "string",
                      "example": "CH"
                    },
                    "continent": {
                      "type": "string",
                      "example": "EU"
                    },
                    "abuse": {
                      "type": "object"
                    },
                    "vt": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid IP address supplied via `?ip=`"
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/ip": {
      "get": {
        "summary": "Client IP address",
        "description": "Returns the detected IP address of the caller, or the `ip` query parameter if provided.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": false,
            "description": "Override: a specific IPv4 or IPv6 address to look up.",
            "schema": {
              "type": "string",
              "examples": [
                "1.1.1.1",
                "2606:4700:4700::1111"
              ]
            }
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "description": "Return JSON instead of plain text. Any value except `false` enables JSON.",
            "schema": {
              "type": "string",
              "example": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "IP address",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "1.2.3.4"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ip": {
                      "type": "string",
                      "example": "1.2.3.4"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid IP address supplied via `?ip=`"
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/country": {
      "get": {
        "summary": "Country code",
        "description": "Returns the ISO 3166-1 alpha-2 country code for the IP.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country code",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "CH"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country": {
                      "type": "string",
                      "example": "CH"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid IP address supplied via `?ip=`"
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/continent": {
      "get": {
        "summary": "Continent code",
        "description": "Returns the two-letter continent code for the IP (EU, NA, AS, …). Not available when using `?ip=`.",
        "parameters": [
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Continent code",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "EU"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "continent": {
                      "type": "string",
                      "example": "EU"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/abuse": {
      "get": {
        "summary": "AbuseIPDB report",
        "description": "Returns threat data from [AbuseIPDB](https://www.abuseipdb.com/) for the IP.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Abuse data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "abuseConfidenceScore": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100,
                      "description": "Confidence score that the IP is abusive (0–100)."
                    },
                    "isTor": {
                      "type": "boolean",
                      "description": "Whether the IP is a known Tor exit node."
                    },
                    "lastReportedAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true,
                      "description": "Timestamp of the last abuse report."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid IP address supplied via `?ip=`"
          },
          "500": {
            "description": "AbuseIPDB service error"
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/vt": {
      "get": {
        "summary": "VirusTotal report",
        "description": "Returns threat data from [VirusTotal](https://www.virustotal.com/) for the IP.",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "json",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "VirusTotal data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "score": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100,
                      "description": "Percentage of engines that flagged the IP as malicious or suspicious."
                    },
                    "country": {
                      "type": "string",
                      "nullable": true,
                      "description": "ISO 3166-1 alpha-2 country code as reported by VirusTotal."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid IP address supplied via `?ip=`"
          },
          "500": {
            "description": "VirusTotal service error"
          },
          "503": {
            "description": "Client IP could not be determined"
          }
        }
      }
    },
    "/schema": {
      "get": {
        "summary": "OpenAPI 3.1 schema",
        "description": "Returns this OpenAPI schema as JSON.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}