{
  "openapi": "3.1.0",
  "info": {
    "title": "iseeu.cc API",
    "version": "1.0.0",
    "description": "What the internet sees about the caller: IP, IP-based location, ASN, TLS, HTTP and request headers. No key, CORS enabled, 60 requests/minute/IP, no logs.",
    "contact": {
      "email": "hello@iseeu.cc",
      "url": "https://iseeu.cc/contact/"
    },
    "termsOfService": "https://iseeu.cc/terms/"
  },
  "externalDocs": {
    "url": "https://iseeu.cc/api/"
  },
  "servers": [
    {
      "url": "https://iseeu.cc"
    }
  ],
  "paths": {
    "/ip": {
      "get": {
        "operationId": "getIp",
        "summary": "Caller's public IP as plain text",
        "responses": {
          "200": {
            "description": "IP address followed by a newline",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "192.0.2.1\n"
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "getRoot",
        "summary": "Plain-text IP for non-browser clients (HTML page when Accept contains text/html)",
        "responses": {
          "200": {
            "description": "IP address followed by a newline",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/json": {
      "get": {
        "operationId": "getInfo",
        "summary": "Everything iseeu.cc can see about the request",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ]
            },
            "description": "`text` returns flat `key: value` lines."
          }
        ],
        "responses": {
          "200": {
            "description": "Full request information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Info"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/geo": {
      "get": {
        "operationId": "getGeo",
        "summary": "IP, location and network",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ]
            },
            "description": "`text` returns flat `key: value` lines."
          }
        ],
        "responses": {
          "200": {
            "description": "Location and network",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Location"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "ip": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "asn": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "asOrganization": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "colo": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/tls": {
      "get": {
        "operationId": "getTls",
        "summary": "TLS and HTTP protocol details",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ]
            },
            "description": "`text` returns flat `key: value` lines."
          }
        ],
        "responses": {
          "200": {
            "description": "TLS details",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Tls"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "httpProtocol": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/ua": {
      "get": {
        "operationId": "getUserAgent",
        "summary": "Parsed User-Agent of the caller",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ]
            },
            "description": "`text` returns flat `key: value` lines."
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed User-Agent (text format returns the raw string)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserAgent"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/headers": {
      "get": {
        "operationId": "getHeaders",
        "summary": "Request headers sent by the caller and added by Cloudflare",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "text"
              ]
            },
            "description": "`text` returns flat `key: value` lines."
          }
        ],
        "responses": {
          "200": {
            "description": "Headers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "headers": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "edgeHeaders": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/rdap": {
      "get": {
        "operationId": "rdapLookup",
        "summary": "RDAP registration data for a domain, IP address/CIDR or AS number",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Summary and raw RDAP JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "domain",
                        "ip",
                        "autnum"
                      ]
                    },
                    "source": {
                      "type": "string"
                    },
                    "bootstrapUpdated": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "summary": {
                      "type": "object"
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not a domain, IP address or AS number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No record, or no RDAP service for that TLD",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "Registry error"
          },
          "504": {
            "description": "Registry timeout"
          }
        }
      }
    },
    "/api/headers-check": {
      "get": {
        "operationId": "headersCheck",
        "summary": "Response headers and security grade for a public URL",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "https://example.com/"
          }
        ],
        "responses": {
          "200": {
            "description": "Headers, redirect hops and grade",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "finalUrl": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "method": {
                      "type": "string"
                    },
                    "hops": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "url": {
                            "type": "string"
                          },
                          "status": {
                            "type": "integer"
                          },
                          "location": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "headers": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "setCookies": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "grade": {
                      "type": "object",
                      "properties": {
                        "score": {
                          "type": "integer"
                        },
                        "grade": {
                          "type": "string"
                        },
                        "checks": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "notes": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "elapsedMs": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "URL not allowed (private address, bad port, not http/https)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "Target unreachable"
          },
          "504": {
            "description": "Target too slow (5 s)"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Info": {
        "type": "object",
        "required": [
          "ip",
          "ipVersion",
          "location",
          "network",
          "tls",
          "http",
          "userAgent",
          "headers",
          "edgeHeaders",
          "time",
          "meta"
        ],
        "properties": {
          "ip": {
            "type": [
              "string",
              "null"
            ],
            "description": "Public IP address of the caller (CF-Connecting-IP)."
          },
          "ipVersion": {
            "type": [
              "integer",
              "null"
            ],
            "enum": [
              4,
              6,
              null
            ]
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "network": {
            "type": "object",
            "properties": {
              "asn": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "asOrganization": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "colo": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "IATA code of the Cloudflare data center that handled the request."
              },
              "clientTcpRttMs": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "clientQuicRttMs": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "deliveryRateBps": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "tls": {
            "$ref": "#/components/schemas/Tls"
          },
          "http": {
            "type": "object",
            "properties": {
              "protocol": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "method": {
                "type": "string"
              },
              "priority": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "acceptEncoding": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "userAgent": {
            "$ref": "#/components/schemas/UserAgent"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Headers the client sent (lower-case names)."
          },
          "edgeHeaders": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Headers added by Cloudflare's edge."
          },
          "time": {
            "type": "object",
            "properties": {
              "server": {
                "type": "string",
                "format": "date-time"
              },
              "serverMs": {
                "type": "integer"
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "docs": {
                "type": "string"
              },
              "privacy": {
                "type": "string"
              },
              "simulated": {
                "type": "boolean",
                "description": "True on a local development server, where network fields are simulated."
              }
            }
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "countryName": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "regionCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "postalCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "metroCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "continent": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ]
          },
          "isEU": {
            "type": "boolean"
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "Tls": {
        "type": "object",
        "properties": {
          "version": {
            "type": [
              "string",
              "null"
            ]
          },
          "cipher": {
            "type": [
              "string",
              "null"
            ]
          },
          "clientHelloLength": {
            "type": [
              "integer",
              "null"
            ]
          },
          "clientCiphersSha1": {
            "type": [
              "string",
              "null"
            ]
          },
          "clientExtensionsSha1": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "UserAgent": {
        "type": "object",
        "properties": {
          "raw": {
            "type": "string"
          },
          "browser": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "major": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "engine": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "os": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "device": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "vendor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "model": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "cpu": {
            "type": "object",
            "properties": {
              "architecture": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "browser",
              "search-crawler",
              "ai-crawler",
              "ai-assistant",
              "social-preview",
              "http-library",
              "cli",
              "headless-browser",
              "monitoring",
              "bot",
              "unknown"
            ]
          },
          "bot": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  },
                  "operator": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "More than 60 requests in a minute from this IP",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}