{
  "openapi": "3.1.0",
  "info": {
    "title": "BotCentral",
    "version": "1.1",
    "summary": "Opt-in catalog of sites that allow AI bots.",
    "description": "The public contract for bot indexing. Search, fetch a site card, watch the change feed. Publish is a private CiteFleet channel."
  },
  "servers": [
    {
      "url": "https://botcentral.org"
    }
  ],
  "tags": [
    {
      "name": "catalog"
    },
    {
      "name": "agents"
    },
    {
      "name": "integrity"
    }
  ],
  "paths": {
    "/v1/search": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Search listed sites",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "verified",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "consent",
            "in": "query",
            "schema": {
              "enum": [
                "retrieve",
                "train",
                "act",
                "cite"
              ]
            }
          },
          {
            "name": "capability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "allow_bots",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "schema": {
              "enum": [
                "card"
              ]
            }
          },
          {
            "name": "intent",
            "in": "query",
            "schema": {
              "enum": [
                "1"
              ]
            },
            "description": "Parse q as natural language."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search hits"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/site/{domain}": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Fetch a 1.1 site card",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Site card"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not listed"
          }
        }
      }
    },
    "/v1/site/{domain}/pages": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Pages on a listed card",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pages"
          },
          "404": {
            "description": "Not listed"
          }
        }
      }
    },
    "/v1/agents": {
      "get": {
        "tags": [
          "agents"
        ],
        "summary": "Known AI agent tokens",
        "responses": {
          "200": {
            "description": "Registry"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "tags": [
          "integrity"
        ],
        "summary": "Catalog change feed",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Publish log"
          }
        }
      }
    },
    "/v1/snapshot": {
      "get": {
        "tags": [
          "integrity"
        ],
        "summary": "Live catalog snapshot + integrity hash",
        "responses": {
          "200": {
            "description": "Snapshot"
          }
        }
      }
    },
    "/v1/probe": {
      "post": {
        "tags": [
          "catalog"
        ],
        "summary": "Probe an origin for listing readiness",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "verifyToken": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Probe report"
          }
        }
      }
    },
    "/v1/schema.json": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "JSON Schema for card 1.1",
        "responses": {
          "200": {
            "description": "JSON Schema"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SiteCard": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "https://botcentral.org/v1/schema.json",
        "title": "BotCentral card",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "botcentral",
          "domain",
          "canonical",
          "name",
          "summary",
          "topics",
          "allow_bots",
          "allow",
          "deny",
          "pointers",
          "pages",
          "updated",
          "verification",
          "consent"
        ],
        "properties": {
          "botcentral": {
            "enum": [
              "1.0",
              "1.1"
            ]
          },
          "domain": {
            "type": "string",
            "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$"
          },
          "canonical": {
            "type": "string",
            "format": "uri"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "summary": {
            "type": "string",
            "minLength": 1
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allow_bots": {
            "type": "boolean"
          },
          "allow": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "deny": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pointers": {
            "type": "object",
            "required": [
              "robots",
              "sitemap",
              "llms"
            ],
            "properties": {
              "robots": {
                "type": "string",
                "format": "uri"
              },
              "sitemap": {
                "type": "string",
                "format": "uri"
              },
              "llms": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "url",
                "rel"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "rel": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                }
              }
            }
          },
          "consent": {
            "type": "object",
            "required": [
              "retrieve",
              "train",
              "act",
              "cite",
              "tdm"
            ],
            "properties": {
              "retrieve": {
                "type": "boolean",
                "description": "RAG / citation / answering"
              },
              "train": {
                "type": "boolean",
                "description": "Foundation-model training"
              },
              "act": {
                "type": "boolean",
                "description": "Agentic tools, MCP, writes"
              },
              "cite": {
                "type": "boolean"
              },
              "tdm": {
                "enum": [
                  "open",
                  "reserved",
                  "licensed"
                ]
              }
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "kind"
              ],
              "properties": {
                "kind": {
                  "enum": [
                    "read",
                    "cite",
                    "search",
                    "mcp",
                    "openapi",
                    "a2a",
                    "iso20022",
                    "checkout",
                    "booking"
                  ]
                },
                "href": {
                  "type": "string",
                  "format": "uri"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "crawl": {
            "type": "object",
            "properties": {
              "delay_ms": {
                "type": "integer"
              },
              "burst": {
                "type": "integer"
              },
              "revalidate_hours": {
                "type": "integer"
              }
            }
          },
          "freshness": {
            "type": "object",
            "properties": {
              "status": {
                "enum": [
                  "fresh",
                  "stale",
                  "unproven"
                ]
              },
              "checked": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "revalidate_hours": {
                "type": "integer"
              }
            }
          },
          "verification": {
            "type": "object",
            "required": [
              "method"
            ],
            "properties": {
              "method": {
                "enum": [
                  "dns-txt",
                  "well-known-file",
                  "pending",
                  "unverified",
                  "stale"
                ]
              },
              "checked": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              }
            }
          },
          "etag": {
            "type": "string"
          },
          "contact": {
            "type": "object",
            "properties": {
              "abuse": {
                "type": "string"
              },
              "publisher": {
                "type": "string"
              },
              "security": {
                "type": "string"
              }
            }
          },
          "policy": {
            "type": "object",
            "properties": {
              "citation": {
                "type": "string"
              },
              "license": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}