{
  "openapi": "3.1.0",
  "info": {
    "title": "ipfast.dev API",
    "version": "7.0",
    "description": "IP geolocation, VPN/proxy detection, threat intelligence, and fraud risk scoring API. 30+ endpoints, sub-5ms response time, powered by the edge."
  },
  "servers": [
    {
      "url": "https://ipfast.dev"
    }
  ],
  "paths": {
    "/json": {
      "get": {
        "operationId": "getIpJson",
        "summary": "Get caller IP geolocation as JSON (24 fields: geo, currency, flag, continent, EU, languages)",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "xml",
                "yaml",
                "csv"
              ]
            }
          },
          {
            "name": "callback",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "JSONP callback"
          }
        ],
        "responses": {
          "200": {
            "description": "IP geolocation data"
          }
        }
      }
    },
    "/json/{ip}": {
      "get": {
        "operationId": "getIpJsonByIP",
        "summary": "Get geolocation for any IP (premium, requires an API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "IPv4 or IPv6 address"
          },
          {
            "name": "modules",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated: country_meta,company,security,threat,risk"
          },
          {
            "name": "apikey",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "API key (bypasses payment)"
          }
        ],
        "responses": {
          "200": {
            "description": "IP geolocation data"
          },
          "401": {
            "description": "Invalid API key"
          }
        }
      }
    },
    "/text": {
      "get": {
        "operationId": "getIpText",
        "summary": "Get IP as plain text",
        "responses": {
          "200": {
            "description": "IP address"
          }
        }
      }
    },
    "/all": {
      "get": {
        "operationId": "getAllInfo",
        "summary": "Get IP + connection + user agent",
        "responses": {
          "200": {
            "description": "Combined data"
          }
        }
      }
    },
    "/country/{ip}": {
      "get": {
        "operationId": "getCountryByIP",
        "summary": "Get country code for any IP (premium)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country code"
          }
        }
      }
    },
    "/country-meta/{ip}": {
      "get": {
        "operationId": "getCountryMeta",
        "summary": "Get country metadata for any IP (starter+ API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country metadata"
          }
        }
      }
    },
    "/company/{ip}": {
      "get": {
        "operationId": "getCompany",
        "summary": "Get company/ASN info for any IP (pro+ API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company info"
          }
        }
      }
    },
    "/distance/{ip1}/{ip2}": {
      "get": {
        "operationId": "getDistance",
        "summary": "Distance between two IPs (pro+ API key)",
        "parameters": [
          {
            "name": "ip1",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip2",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Distance result"
          }
        }
      }
    },
    "/security/{ip}": {
      "get": {
        "operationId": "getSecurity",
        "summary": "VPN/proxy/Tor/datacenter detection (business+ API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Security classification with is_vpn, is_proxy, is_tor, is_datacenter, threat_score, classification, hostname"
          }
        }
      }
    },
    "/threat/{ip}": {
      "get": {
        "operationId": "getThreat",
        "summary": "Threat intelligence with known attacker detection (business+ API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Threat level, categories, is_known_attacker, is_known_abuser, recommendation"
          }
        }
      }
    },
    "/risk/{ip}": {
      "get": {
        "operationId": "getRisk",
        "summary": "Comprehensive fraud risk scoring 0-100 (business+ API key)",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Risk score, anonymizer breakdown, network analysis, country risk, recommendation, reasons"
          }
        }
      }
    },
    "/bulk": {
      "post": {
        "operationId": "bulkLookup",
        "summary": "Batch IP lookup (pro+ API key)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ips": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results"
          }
        }
      }
    },
    "/country": {
      "get": {
        "operationId": "getCountry",
        "summary": "Get country code",
        "responses": {
          "200": {
            "description": "Country code"
          }
        }
      }
    },
    "/city": {
      "get": {
        "operationId": "getCity",
        "summary": "Get city name",
        "responses": {
          "200": {
            "description": "City name"
          }
        }
      }
    },
    "/region": {
      "get": {
        "operationId": "getRegion",
        "summary": "Get region/state",
        "responses": {
          "200": {
            "description": "Region"
          }
        }
      }
    },
    "/timezone": {
      "get": {
        "operationId": "getTimezone",
        "summary": "Get IANA timezone",
        "responses": {
          "200": {
            "description": "Timezone"
          }
        }
      }
    },
    "/coordinates": {
      "get": {
        "operationId": "getCoordinates",
        "summary": "Get lat,lon",
        "responses": {
          "200": {
            "description": "Coordinates"
          }
        }
      }
    },
    "/asn": {
      "get": {
        "operationId": "getAsn",
        "summary": "Get ASN info",
        "responses": {
          "200": {
            "description": "ASN"
          }
        }
      }
    },
    "/postal": {
      "get": {
        "operationId": "getPostal",
        "summary": "Get postal code",
        "responses": {
          "200": {
            "description": "Postal code"
          }
        }
      }
    },
    "/connection": {
      "get": {
        "operationId": "getConnection",
        "summary": "Get connection/TLS details",
        "responses": {
          "200": {
            "description": "Connection info"
          }
        }
      }
    },
    "/useragent": {
      "get": {
        "operationId": "getUserAgent",
        "summary": "Get parsed user agent",
        "responses": {
          "200": {
            "description": "User agent info"
          }
        }
      }
    },
    "/headers": {
      "get": {
        "operationId": "getHeaders",
        "summary": "Get request headers",
        "responses": {
          "200": {
            "description": "Headers"
          }
        }
      }
    }
  }
}