{
  "openapi": "3.1.0",
  "info": {
    "title": "Built Logic public machine interface",
    "description": "Public documentation and enquiry interface for Built Logic, the AI specialist for the UK built environment. Private webhooks and chat endpoints are not part of this specification.",
    "version": "1.0.0",
    "contact": {
      "name": "Built Logic",
      "email": "hello@builtlogic.ai",
      "url": "https://www.builtlogic.ai/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.builtlogic.ai",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "docs", "description": "Machine-readable documentation" },
    { "name": "enquiry", "description": "Public enquiry form" }
  ],
  "paths": {
    "/docs": {
      "get": {
        "operationId": "getPublicDocs",
        "tags": ["docs"],
        "summary": "Public machine-interface documentation",
        "description": "Returns markdown documentation for agents: authentication, endpoints, and example requests.",
        "responses": {
          "200": {
            "description": "Markdown documentation",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": ["docs"],
        "summary": "OpenAPI specification",
        "description": "Returns this OpenAPI 3.1 document.",
        "responses": {
          "200": {
            "description": "OpenAPI document",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": ["docs"],
        "summary": "llms.txt page index",
        "description": "Returns the site index written for language models.",
        "responses": {
          "200": {
            "description": "Plain-text index",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "operationId": "getHomepageMarkdown",
        "tags": ["docs"],
        "summary": "Homepage markdown",
        "description": "Markdown copy of the homepage. The HTML homepage also negotiates Accept: text/markdown.",
        "responses": {
          "200": {
            "description": "Homepage markdown",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "tags": ["docs"],
        "summary": "RFC 9727 API catalog",
        "description": "Linkset pointing at the OpenAPI document and markdown docs.",
        "responses": {
          "200": {
            "description": "API catalog linkset",
            "content": {
              "application/linkset+json": {
                "schema": { "$ref": "#/components/schemas/ApiCatalog" }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContactEnquiry",
        "tags": ["enquiry"],
        "summary": "Submit a contact enquiry",
        "description": "Website enquiry form. Origin-checked for browser posts from builtlogic.ai. Agents that cannot satisfy the origin check should email hello@builtlogic.ai.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContactEnquiry" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry accepted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactSuccess" }
              }
            }
          },
          "400": {
            "description": "Invalid name or email",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactError" }
              }
            }
          },
          "403": {
            "description": "Origin not allowed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactError" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactError" }
              }
            }
          },
          "502": {
            "description": "Enquiry could not be sent",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactError" }
              }
            }
          }
        }
      }
    },
    "/api/{path}": {
      "get": {
        "operationId": "getUnknownApiPath",
        "tags": ["docs"],
        "summary": "Unknown API path",
        "description": "Unknown /api/ paths are not part of the public interface. They return RFC 9457 application/problem+json. Existing JSON handlers such as POST /api/contact keep {success, error}.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "404": {
            "description": "No public API operation exists at this path",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactEnquiry": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 200, "description": "Person's name" },
          "email": { "type": "string", "format": "email", "maxLength": 200, "description": "Reply email" },
          "company": { "type": "string", "maxLength": 200 },
          "role": { "type": "string", "maxLength": 200 },
          "business_type": { "type": "string", "maxLength": 200 },
          "topic": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } }
            ],
            "description": "What the enquiry is about"
          },
          "context": { "type": "string", "maxLength": 4000, "description": "Free-text message" }
        },
        "additionalProperties": true
      },
      "ContactSuccess": {
        "type": "object",
        "required": ["success"],
        "properties": {
          "success": { "type": "boolean", "enum": [true] }
        }
      },
      "ContactError": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": { "type": "string" }
        }
      },
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status", "code", "message", "resolution"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "code": { "type": "string" },
          "message": { "type": "string" },
          "resolution": { "type": "string" },
          "instance": { "type": "string" }
        }
      },
      "ApiCatalog": {
        "type": "object",
        "required": ["linkset"],
        "properties": {
          "linkset": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}