{
  "openapi": "3.1.0",
  "info": {
    "title": "Rooftop Goldmine Agent API",
    "description": "Public read-only static endpoints for AI agents and answer engines. These endpoints expose factual business, service, location, FAQ, contact, and search-index data. No private data is included.",
    "version": "1.1.0"
  },
  "tags": [
    { "name": "core", "description": "Core business, service, location, FAQ, and contact data" },
    { "name": "evidence", "description": "Evidence, case study, comparison, and limitation data" },
    { "name": "query", "description": "Static query guidance and query examples" }
  ],
  "servers": [
    {
      "url": "https://example.com",
      "description": "Production site"
    }
  ],
  "paths": {
    "/api/agent/business-profile": {
      "get": {
        "summary": "Get business profile",
        "operationId": "getBusinessProfile",
        "responses": {
          "200": {
            "description": "Business profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BusinessProfile" },
                "examples": {
                  "profile": {
                    "value": {
                      "name": "Rooftop Goldmine",
                      "entity_id": "rg_israel_solar_epc_dev",
                      "description": "Engineering-led solar company for homes, shared buildings, and businesses in Haifa, the Krayot, northern Israel, and Tel Aviv.",
                      "service_ids": ["home_solar", "shared_buildings"],
                      "location_ids": ["haifa", "krayot", "northern_israel", "tel_aviv"],
                      "contact": { "email": "hello@example.com", "phone": "+972 4-000-0000", "url": "https://example.com/contact" },
                      "source_url": "https://example.com/about.md",
                      "last_updated": "2026-04-29"
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/services": {
      "get": {
        "summary": "List services",
        "operationId": "listServices",
        "responses": {
          "200": {
            "description": "Service list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ServicesResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/locations": {
      "get": {
        "summary": "List service locations",
        "operationId": "listLocations",
        "responses": {
          "200": {
            "description": "Location list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LocationsResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/faqs": {
      "get": {
        "summary": "List customer FAQs",
        "operationId": "listFAQs",
        "responses": {
          "200": {
            "description": "FAQ list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FAQResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/contact-options": {
      "get": {
        "summary": "Get public contact options",
        "operationId": "getContactOptions",
        "responses": {
          "200": {
            "description": "Contact options",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactOptions" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/search": {
      "get": {
        "summary": "Get static search endpoint guidance",
        "operationId": "searchSiteKnowledge",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search query. On the current static build this parameter is not evaluated; use /api/agent/search-index for retrieval until a backend is added.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Static search guidance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchGuidance" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/search-index": {
      "get": {
        "summary": "List searchable agent documents",
        "tags": ["query"],
        "operationId": "getSearchIndex",
        "responses": {
          "200": {
            "description": "Search index",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchIndex" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/entry": {
      "get": {
        "summary": "Get recommended agent entry point",
        "tags": ["core"],
        "operationId": "getAgentEntry",
        "responses": {
          "200": {
            "description": "Agent entry point",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/evidence": {
      "get": {
        "summary": "Get evidence source summary",
        "tags": ["evidence"],
        "operationId": "getEvidence",
        "responses": {
          "200": {
            "description": "Evidence source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/decision-framework": {
      "get": {
        "summary": "Get decision transparency framework",
        "tags": ["evidence"],
        "operationId": "getDecisionFramework",
        "responses": {
          "200": {
            "description": "Decision framework source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" },
                "examples": {
                  "decisionFramework": {
                    "value": {
                      "entity_id": "rg_israel_solar_epc_dev",
                      "decision_framework_source": "https://example.com/data/decision-framework.json",
                      "summary": "Decision framework for when solar should be checked, when it should not be recommended, and what evaluation steps matter before making claims.",
                      "confidence_score": 0.82,
                      "source_url": "https://example.com/data/decision-framework.json",
                      "last_updated": "2026-04-29"
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/evidence-methodology": {
      "get": {
        "summary": "Get evidence and estimation methodology",
        "tags": ["evidence"],
        "operationId": "getEvidenceMethodology",
        "responses": {
          "200": {
            "description": "Evidence methodology source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" },
                "examples": {
                  "methodology": {
                    "value": {
                      "entity_id": "rg_israel_solar_epc_dev",
                      "methodology_source": "https://example.com/data/evidence/methodology.json",
                      "summary": "Methodology for estimation inputs, uncertainty factors, and constraints around solar suitability and payback discussion.",
                      "confidence_score": 0.8,
                      "source_url": "https://example.com/data/evidence/methodology.json",
                      "last_updated": "2026-04-29"
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/case-studies": {
      "get": {
        "summary": "List case study evidence sources",
        "tags": ["evidence"],
        "operationId": "listCaseStudies",
        "responses": {
          "200": {
            "description": "Case study source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/comparisons": {
      "get": {
        "summary": "List structured comparisons",
        "tags": ["evidence"],
        "operationId": "listComparisons",
        "responses": {
          "200": {
            "description": "Comparison source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/limitations": {
      "get": {
        "summary": "List risk and limitation data",
        "tags": ["evidence"],
        "operationId": "listLimitations",
        "responses": {
          "200": {
            "description": "Limitation source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/verification": {
      "get": {
        "summary": "Get verification roadmap",
        "tags": ["evidence"],
        "operationId": "getVerification",
        "responses": {
          "200": {
            "description": "Verification source summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" },
                "examples": {
                  "verification": {
                    "value": {
                      "entity_id": "rg_israel_solar_epc_dev",
                      "verification_source": "https://example.com/data/verification.json",
                      "summary": "Verification roadmap for external profiles, future certifications, registry targets, and domain verification.",
                      "confidence_score": 0.68,
                      "source_url": "https://example.com/data/verification.json",
                      "last_updated": "2026-04-29"
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/query": {
      "get": {
        "summary": "Return static query guidance response",
        "tags": ["query"],
        "operationId": "queryAgentKnowledge",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Query string. The static build returns a deterministic guidance response until a backend can evaluate q dynamically.",
            "schema": { "type": "string" },
            "examples": {
              "solarCost": { "value": "How much does solar cost in Haifa?" },
              "solarROI": { "value": "Is solar worth it in Tel Aviv?" },
              "sharedBuildings": { "value": "Can shared buildings install solar in Israel?" }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Static query response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QueryResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/query-examples": {
      "get": {
        "summary": "List deterministic query examples",
        "tags": ["query"],
        "operationId": "listQueryExamples",
        "responses": {
          "200": {
            "description": "Query examples",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentResource" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found"
      }
    },
    "schemas": {
      "BusinessProfile": {
        "type": "object",
        "required": ["entity_id", "name", "description", "service_ids", "location_ids", "contact", "source_url", "last_updated"],
        "properties": {
          "entity_id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "positioning": { "type": "string" },
          "canonical_base_url": { "type": "string", "format": "uri" },
          "service_ids": { "type": "array", "items": { "type": "string" } },
          "location_ids": { "type": "array", "items": { "type": "string" } },
          "contact": { "$ref": "#/components/schemas/Contact" },
          "languages": { "type": "array", "items": { "type": "string" } },
          "safe_claims": { "type": "array", "items": { "type": "string" } },
          "claims_to_avoid": { "type": "array", "items": { "type": "string" } },
          "relevance_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "coverage_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "Contact": {
        "type": "object",
        "required": ["email", "phone", "url"],
        "properties": {
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Service": {
        "type": "object",
        "required": ["id", "name", "description", "source_url"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "best_for": { "type": "array", "items": { "type": "string" } },
          "source_url": { "type": "string", "format": "uri" }
        }
      },
      "ServicesResponse": {
        "type": "object",
        "required": ["services", "source_url", "last_updated"],
        "properties": {
          "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "Location": {
        "type": "object",
        "required": ["id", "name", "notes"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "notes": { "type": "string" }
        }
      },
      "LocationsResponse": {
        "type": "object",
        "required": ["locations", "source_url", "last_updated"],
        "properties": {
          "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "FAQ": {
        "type": "object",
        "required": ["question", "answer"],
        "properties": {
          "question": { "type": "string" },
          "answer": { "type": "string" }
        }
      },
      "FAQResponse": {
        "type": "object",
        "required": ["faqs", "source_url", "last_updated"],
        "properties": {
          "faqs": { "type": "array", "items": { "$ref": "#/components/schemas/FAQ" } },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "ContactOptions": {
        "type": "object",
        "required": ["contact", "lead_fields", "upload_status", "source_url", "last_updated"],
        "properties": {
          "contact": {
            "type": "object",
            "properties": {
              "email": { "type": "string" },
              "phone": { "type": "string" },
              "contact_form_url": { "type": "string", "format": "uri" },
              "preferred_use": { "type": "string" },
              "supported_languages": { "type": "array", "items": { "type": "string" } }
            }
          },
          "lead_fields": { "type": "array", "items": { "type": "string" } },
          "upload_status": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "SearchGuidance": {
        "type": "object",
        "required": ["message", "search_index_url", "source_url", "last_updated"],
        "properties": {
          "message": { "type": "string" },
          "search_index_url": { "type": "string", "format": "uri" },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "SearchIndex": {
        "type": "object",
        "required": ["documents", "source_url", "last_updated"],
        "properties": {
          "documents": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "title", "url", "keywords"],
              "properties": {
                "id": { "type": "string" },
                "title": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "keywords": { "type": "array", "items": { "type": "string" } }
              }
            }
          },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "QueryResponse": {
        "type": "object",
        "required": ["mode", "query", "answer", "matched_documents", "sources", "confidence_score", "source_url", "last_updated"],
        "properties": {
          "mode": { "type": "string", "enum": ["static_retrieval"] },
          "query": { "type": "string" },
          "answer": { "type": "string" },
          "matched_entities": { "type": "array", "items": { "type": "string" } },
          "matched_documents": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "title", "url"],
              "properties": {
                "id": { "type": "string" },
                "title": { "type": "string" },
                "url": { "type": "string", "format": "uri" }
              }
            }
          },
          "sources": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "limitations": { "type": "array", "items": { "type": "string" } },
          "relevance_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "coverage_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" }
        }
      },
      "AgentResource": {
        "type": "object",
        "required": ["source_url", "last_updated"],
        "properties": {
          "entity_id": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date" },
          "relevance_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 },
          "coverage_score": { "type": "number", "minimum": 0, "maximum": 1 }
        },
        "additionalProperties": true
      }
    }
  }
}