{
  "openapi": "3.0.3",
  "info": {
    "title": "RealBots – AI bot verification API",
    "version": "1.0.0",
    "description": "Check whether a request claiming to be an AI crawler (GPTBot, ClaudeBot, PerplexityBot, Googlebot, Applebot and others) really comes from the operator's officially published IP ranges, and verify Web Bot Auth (HTTP Message Signatures) from signed AI agents. Data refreshed daily from each operator's official lists. Docs: https://aibots.kaderagha.com/api-docs",
    "contact": { "name": "RealBots", "url": "https://aibots.kaderagha.com/contact" },
    "termsOfService": "https://aibots.kaderagha.com/terms"
  },
  "servers": [{ "url": "https://aibots.kaderagha.com/api/aibots" }],
  "security": [{ "ApiKeyHeader": [] }],
  "paths": {
    "/v1/verify": {
      "get": {
        "operationId": "verifyBot",
        "summary": "Verify an AI crawler by IP + user agent",
        "description": "Returns which bot the user agent claims to be and whether the IP is inside that operator's published ranges.",
        "parameters": [
          { "name": "ip", "in": "query", "required": true, "description": "Client IP (IPv4 or IPv6)", "schema": { "type": "string", "example": "20.171.207.10" } },
          { "name": "ua", "in": "query", "required": true, "description": "The request's User-Agent header", "schema": { "type": "string", "example": "Mozilla/5.0; compatible; GPTBot/1.4; +https://openai.com/gptbot" } }
        ],
        "responses": {
          "200": { "description": "Verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/verify-signature": {
      "post": {
        "operationId": "verifySignature",
        "summary": "Verify a Web Bot Auth signature",
        "description": "Verifies the Signature / Signature-Input / Signature-Agent headers of a request from a signed AI agent (draft-ietf-webbotauth-httpsig-protocol, Ed25519). Keys of known signing agents (Google-Agent, ChatGPT, Browserbase, You.com) are built in; others are fetched from the agent's key directory.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequest" } } }
        },
        "responses": {
          "200": { "description": "Result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureResult" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "usage",
        "summary": "Current month's usage for your key",
        "responses": {
          "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } },
    "responses": {
      "Error": {
        "description": "Error",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }
      }
    },
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "gptbot" },
          "name": { "type": "string", "example": "GPTBot" },
          "operator": { "type": "string", "example": "OpenAI" },
          "kind": { "type": "string", "enum": ["training", "crawler", "search", "user", "ads", "token"] }
        }
      },
      "VerifyResult": {
        "type": "object",
        "properties": {
          "verdict": { "type": "string", "enum": ["verified", "fake", "unverifiable", "not_a_bot", "invalid_ip"] },
          "bot": { "$ref": "#/components/schemas/Bot" },
          "reason": { "type": "string" },
          "feed_generated": { "type": "string", "nullable": true }
        }
      },
      "SignatureRequest": {
        "type": "object",
        "required": ["url", "headers"],
        "properties": {
          "method": { "type": "string", "default": "GET" },
          "url": { "type": "string", "example": "https://your-site.com/page" },
          "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers incl. Signature, Signature-Input, Signature-Agent" }
        }
      },
      "SignatureResult": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["valid", "invalid", "nokey", "unsupported", "unsigned"] },
          "agent": { "type": "string", "nullable": true },
          "reason": { "type": "string" }
        }
      },
      "Usage": {
        "type": "object",
        "properties": { "plan": { "type": "string" }, "period": { "type": "string" }, "used": { "type": "integer" }, "quota": { "type": "integer", "nullable": true, "description": "Monthly call quota; null for RapidAPI consumers (see your RapidAPI dashboard)." }, "note": { "type": "string" } }
      }
    }
  }
}