{
  "openapi": "3.1.0",
  "info": {
    "title": "BOT Intelligence Network",
    "version": "0.2.0",
    "description": "A public observation exchange: requests contribute coarse telemetry; later clients retrieve aggregated knowledge."
  },
  "servers": [
    {
      "url": "https://ninizemi.com/bot-intelligence"
    }
  ],
  "paths": {
    "/v1/observe": {
      "get": {
        "operationId": "v1_observe",
        "summary": "Your coarse request context and recording receipt",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "operationId": "v1_stats",
        "summary": "Traffic distributions and all-time daily counts",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/patterns": {
      "get": {
        "operationId": "v1_patterns",
        "summary": "Observed country/ASN/client-family combinations; groups of at least 3",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "operationId": "v1_changes",
        "summary": "Difference between the two most recent snapshots",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/bots.json": {
      "get": {
        "operationId": "v1_bots_json",
        "summary": "Known crawler profiles and unverified individual User-Agent observations",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/updates.json": {
      "get": {
        "operationId": "v1_updates_json",
        "summary": "New daily User-Agent observations and catalog additions; paginated",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "description": "Cursor from next_before_id; older events remain available through pagination.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/bot-daily.json": {
      "get": {
        "operationId": "v1_bot-daily_json",
        "summary": "Daily UTC claimed bot counts by profile",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/bot-weekly.json": {
      "get": {
        "operationId": "v1_bot-weekly_json",
        "summary": "Weekly UTC claimed bot counts by profile, Monday through Sunday",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/datasets/latest.json": {
      "get": {
        "operationId": "datasets_latest_json",
        "summary": "Complete latest aggregate snapshot",
        "parameters": [
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous aggregate response"
          }
        ],
        "responses": {
          "200": {
            "description": "Public JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "description": "The published snapshot has not changed"
          },
          "429": {
            "description": "Short burst limit exceeded; retry after the indicated delay"
          },
          "503": {
            "description": "Temporarily unavailable; retry later"
          }
        }
      }
    },
    "/v1/bots/{slug}.json": {
      "get": {
        "operationId": "get_bot",
        "summary": "Get one sourced bot profile and unverified observations",
        "parameters": [
          {
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "gptbot",
                "oai-searchbot",
                "chatgpt-user",
                "oai-adsbot",
                "claudebot",
                "claude-searchbot",
                "claude-user",
                "googlebot",
                "googlebot-image",
                "googleother"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bot profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "description": "Unknown bot"
          }
        }
      }
    }
  }
}