{
  "openapi": "3.1.1",
  "info": {
    "title": "treetown public content API",
    "version": "1.0.0",
    "description": "Read the public site, retrieve page text, or search page and project descriptions. No authentication or write operations. External websites are not searched."
  },
  "servers": [
    {
      "url": "https://logits.ml"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Agent guide and Markdown access",
    "url": "https://logits.ml/agents.md"
  },
  "paths": {
    "/api/site": {
      "get": {
        "operationId": "getTreetownSite",
        "summary": "Read the complete site overview, pages, and navigation",
        "responses": {
          "200": {
            "description": "Public site content and links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages": {
      "get": {
        "operationId": "getTreetownPage",
        "summary": "Read one public page as structured data and Markdown",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "description": "Canonical page path. Defaults to the homepage.",
            "schema": {
              "type": "string",
              "default": "/",
              "examples": [
                "/",
                "/link-4"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page content, canonical URL, publication status, and Markdown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "404": {
            "description": "An invalid query or unknown page. The error field explains the problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchTreetown",
        "summary": "Search public page and project descriptions",
        "description": "Case-insensitive search. All query words must match. Title matches rank first. An empty results array means no matches.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search words, for example mguide or research.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching pages and links with canonical URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "400": {
            "description": "An invalid query or unknown page. The error field explains the problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Link": {
        "type": "object",
        "required": [
          "id",
          "label",
          "href",
          "url",
          "description",
          "kind",
          "external"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "href": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "external": {
            "type": "boolean"
          }
        }
      },
      "Page": {
        "type": "object",
        "required": [
          "path",
          "title",
          "description",
          "status",
          "content",
          "links",
          "url",
          "markdown"
        ],
        "properties": {
          "path": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "published",
              "placeholder"
            ]
          },
          "content": {
            "type": "string"
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string"
          }
        }
      },
      "Site": {
        "type": "object",
        "required": [
          "version",
          "name",
          "url",
          "description",
          "language",
          "scope",
          "pages",
          "links",
          "documentation",
          "openapi"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "pages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Page"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            }
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "title",
          "description",
          "url",
          "kind",
          "status"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "published",
              "placeholder",
              "external"
            ]
          }
        }
      },
      "Search": {
        "type": "object",
        "required": [
          "query",
          "scope",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "availablePaths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}