{
  "openapi": "3.1.0",
  "info": {
    "title": "BlockWill Public API",
    "version": "1.0.0",
    "summary": "Read-only content, FAQ, schema, and natural-language query endpoints.",
    "description": "Public, read-only API for BlockWill — a digital inheritance and estate-planning platform. These endpoints expose marketing/product content for AI agents and require no authentication. Programmatic account/partner access ships with the Q1 2026 launch; see /auth.md.",
    "contact": {
      "name": "BlockWill",
      "email": "support@blockwill.io",
      "url": "https://www.blockwill.io/contact-us"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://www.blockwill.io",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer portal",
    "url": "https://www.blockwill.io/developers"
  },
  "tags": [
    {
      "name": "content",
      "description": "Structured product and marketing content"
    },
    {
      "name": "query",
      "description": "Natural-language search over public content"
    },
    {
      "name": "agent-auth",
      "description": "Future programmatic access (pre-launch)"
    }
  ],
  "paths": {
    "/api/content": {
      "get": {
        "operationId": "getPlatformContent",
        "tags": [
          "content"
        ],
        "summary": "Get comprehensive platform content",
        "description": "Returns structured JSON describing the problem BlockWill solves, its products, security, asset types, audience, use cases, differentiators, and timeline.",
        "responses": {
          "200": {
            "description": "Platform content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Content"
                }
              }
            }
          }
        }
      }
    },
    "/api/faq": {
      "get": {
        "operationId": "getFaqs",
        "tags": [
          "content"
        ],
        "summary": "Get all FAQs",
        "description": "Returns every FAQ grouped by category (general, launch, product, security, pricing, legal, benefits, technical).",
        "responses": {
          "200": {
            "description": "FAQ collection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaqCollection"
                }
              }
            }
          }
        }
      }
    },
    "/api/schema": {
      "get": {
        "operationId": "getSchemaOrgGraph",
        "tags": [
          "content"
        ],
        "summary": "Get the schema.org JSON-LD graph",
        "description": "Returns the complete schema.org JSON-LD graph (Organization, WebSite, SoftwareApplication, FAQPage, Service, Product, HowTo).",
        "responses": {
          "200": {
            "description": "JSON-LD graph",
            "content": {
              "application/ld+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/ask": {
      "post": {
        "operationId": "askQuestion",
        "tags": [
          "query"
        ],
        "summary": "Ask a natural-language question (NLWeb)",
        "description": "NLWeb endpoint. Submit a natural-language query and receive matched passages from the public content and FAQ. Set streaming=true for a Server-Sent Events response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matched results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AskResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Missing query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpJsonRpc",
        "tags": [
          "query"
        ],
        "summary": "Model Context Protocol endpoint (JSON-RPC 2.0)",
        "description": "Streamable HTTP MCP server. POST JSON-RPC 2.0 messages (initialize, tools/list, tools/call). Tools: get_overview, search_faqs, get_pricing, compare_alternatives.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "operationId": "getProtectedApiRoot",
        "tags": [
          "agent-auth"
        ],
        "summary": "Versioned API root (authentication required — pre-launch)",
        "description": "The authenticated programmatic API. Currently returns 401 with a WWW-Authenticate hint pointing at the OAuth protected-resource metadata. See /auth.md.",
        "security": [
          {
            "agentBearer": []
          }
        ],
        "responses": {
          "401": {
            "description": "Authentication required",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer challenge with resource_metadata pointer",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token for the future authenticated API. Discovery: /.well-known/oauth-protected-resource. Agent onboarding: /auth.md."
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded (60 requests/minute per IP). Retry after the Retry-After interval.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Limit": {
            "description": "Requests allowed per window.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "description": "Requests remaining in the current window.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix epoch (seconds) when the window resets.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Content": {
        "type": "object",
        "description": "Comprehensive platform content.",
        "properties": {
          "platform": {
            "type": "object"
          },
          "problem": {
            "type": "object"
          },
          "solution": {
            "type": "object"
          },
          "security": {
            "type": "object"
          },
          "assetTypes": {
            "type": "object"
          },
          "pricing": {
            "type": "object"
          },
          "targetAudience": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "useCases": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "faqs": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "differentiators": {
            "type": "object"
          },
          "timeline": {
            "type": "object"
          }
        }
      },
      "FaqCollection": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "totalQuestions": {
            "type": "integer"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "AskRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural-language question."
          },
          "streaming": {
            "type": "boolean",
            "default": false,
            "description": "Return SSE stream."
          }
        }
      },
      "AskResponse": {
        "type": "object",
        "properties": {
          "_meta": {
            "type": "object",
            "properties": {
              "response_type": {
                "type": "string",
                "enum": [
                  "results",
                  "no_results"
                ]
              },
              "version": {
                "type": "string"
              }
            }
          },
          "query": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}