{"openapi":"3.1.0","info":{"title":"Ownerproof Public API","version":"1.0.0","summary":"Public and sandbox HTTP API for Ownerproof.","description":"Ownerproof publishes a no-key public API for product facts, developer discovery, and a labeled HVAC sandbox business. Authenticated owner APIs use the Ownerproof session cookie and the named OAuth scopes below. Request the least privilege that completes the job. Versioning and sunset: see https://ownerproof.io/api/deprecation. Breaking changes are advertised with Deprecation and Sunset headers (RFC 9745 / RFC 8594) at least 180 days before a path is removed.","contact":{"name":"Ownerproof LLC","email":"sales@ownerproof.io","url":"https://ownerproof.io"},"license":{"name":"Proprietary","url":"https://ownerproof.io/terms"}},"externalDocs":{"description":"Ownerproof developer resources, CLI, and deprecation policy","url":"https://ownerproof.io/developers"},"servers":[{"url":"https://ownerproof.io","description":"Production"}],"tags":[{"name":"Public","description":"Unauthenticated endpoints. No API key required."},{"name":"Sandbox","description":"Self-serve sample data for agent onboarding."},{"name":"MCP","description":"Model Context Protocol Streamable HTTP transport."}],"paths":{"/healthz":{"get":{"operationId":"getHealthz","summary":"Liveness probe","description":"Returns process liveness and build provenance. Use this to confirm the origin is up before calling other endpoints.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthzResponse","type":"object","properties":{"status":{"type":"string","example":"ok"},"build":{"type":"object"}},"required":["status"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public":{"get":{"operationId":"getPublicCatalog","summary":"Public API catalog","description":"Lists the Ownerproof public API, documentation links, free-tier quiz, sandbox, OpenAPI, and MCP entry points. No authentication.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCatalog","type":"object","properties":{"product":{"type":"string"},"whenToUse":{"type":"string"},"freeTier":{"type":"string"},"links":{"type":"object"},"scopes":{"type":"object"}},"required":["product","links"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/product":{"get":{"operationId":"getPublicProduct","summary":"Product facts","description":"Returns a structured summary of what Ownerproof is, who it is for, pricing at a high level, and how agents should call it.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"Product facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProduct","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"audience":{"type":"string"},"whenToUse":{"type":"string"},"contact":{"type":"object"}},"required":["name","description"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/sandbox/sample-business":{"get":{"operationId":"getSandboxSampleBusiness","summary":"Sandbox sample business","description":"Returns a clearly labeled fictional HVAC company for agent connection tests. This is not a real customer. Optional bearer token with read:public is accepted but not required.","tags":["Sandbox"],"deprecated":false,"security":[{"OAuth2":["read:public"]},{}],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"Sample business","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleBusiness","type":"object","properties":{"sample":{"type":"boolean","const":true},"business":{"type":"object","properties":{"name":{"type":"string"},"industry":{"type":"string"},"location":{"type":"string"},"revenueUsd":{"type":"integer"}},"required":["name","industry"]}},"required":["sample","business"]}}}},"401":{"description":"Missing or invalid sandbox token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/sandbox/token":{"post":{"operationId":"createSandboxToken","summary":"Issue a sandbox access token","description":"Self-serve client-credentials token for the read:public sandbox. No client secret is required. The token only authorizes public sample data.","tags":["Sandbox"],"deprecated":false,"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxTokenRequest","type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"scope":{"type":"string","example":"read:public"}}}}}},"responses":{"200":{"description":"Access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxToken","type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"bearer"},"scope":{"type":"string","example":"read:public"},"expires_in":{"type":"integer"}},"required":["access_token","token_type","scope"]}}}},"400":{"description":"Unsupported grant or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiJson","summary":"OpenAPI document (JSON)","description":"Returns this OpenAPI 3.1 document so agents can bind tools and understand scoped permissions.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument","type":"object","properties":{"openapi":{"type":"string","example":"3.1.0"},"info":{"type":"object"},"paths":{"type":"object"},"components":{"type":"object"}},"required":["openapi","info","paths"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/openapi.yaml":{"get":{"operationId":"getOpenApiYaml","summary":"OpenAPI document (YAML)","description":"YAML rendering of the same OpenAPI 3.1 document published at /openapi.json.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/yaml"]},"description":"This endpoint always responds with application/yaml. Use /openapi.json for the JSON rendering."}],"responses":{"200":{"description":"OpenAPI 3.1 document in YAML","content":{"application/yaml":{"schema":{"$ref":"#/components/schemas/OpenApiYaml","type":"string","contentMediaType":"application/yaml"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"operationId":"postMcp","summary":"MCP Streamable HTTP endpoint","description":"JSON-RPC MCP endpoint using Streamable HTTP. Supports initialize, tools/list, and tools/call for public Ownerproof tools.","tags":["MCP"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json","text/event-stream","application/json, text/event-stream"]},"description":"Streamable HTTP requires application/json and/or text/event-stream. JSON-only initialize is supported; SSE-only initialize returns event: message."},{"name":"MCP-Protocol-Version","in":"header","required":false,"schema":{"type":"string","enum":["2024-11-05","2025-03-26","2025-06-18"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest","type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC result. Streamable HTTP returns text/event-stream when the client accepts only that type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse","type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":{"type":"object"},"error":{"type":"object"}},"required":["jsonrpc"]}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/McpEventStream","type":"string","contentMediaType":"text/event-stream"}}}},"202":{"description":"Notification accepted"},"400":{"description":"Invalid JSON-RPC","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed for this Accept header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"406":{"description":"Neither application/json nor text/event-stream is acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getMcpSse","summary":"MCP Streamable HTTP SSE stream","description":"Opens a Streamable HTTP event stream. POST JSON-RPC to the same path for initialize, tools/list, and tools/call.","tags":["MCP"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json","text/event-stream","application/json, text/event-stream"]},"description":"Streamable HTTP requires application/json and/or text/event-stream. JSON-only initialize is supported; SSE-only initialize returns event: message."},{"name":"MCP-Protocol-Version","in":"header","required":false,"schema":{"type":"string","enum":["2024-11-05","2025-03-26","2025-06-18"]}}],"responses":{"200":{"description":"text/event-stream","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/McpEventStream","type":"string","contentMediaType":"text/event-stream"}}}},"405":{"description":"GET requires Accept: text/event-stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/quiz/questions":{"get":{"operationId":"getQuizQuestions","summary":"Free exit-readiness quiz questions","description":"Public quiz question bank used by the free Ownerproof assessment. No authentication. This is the existing human quiz, exposed for agents that want to run the same flow.","tags":["Public"],"deprecated":false,"security":[],"parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"These operations respond with application/json only. Markdown and HTML negotiation applies to the agent pages, not to this API surface."}],"responses":{"200":{"description":"Quiz questions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuizQuestions","type":"object","properties":{"questions":{"type":"array","items":{"type":"object"}}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"Named OAuth scopes for least-privilege access. The sandbox token endpoint issues read:public. Owner scopes describe the authenticated session API; request only what the job needs.","flows":{"clientCredentials":{"tokenUrl":"https://ownerproof.io/api/public/sandbox/token","scopes":{"read:public":"Read public Ownerproof product facts, developer resources, and sandbox sample data. No customer records."}}}},"CookieAuth":{"type":"apiKey","in":"cookie","name":"ownerproof.sid","description":"Ownerproof web session cookie used by the authenticated owner API."}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]},"HealthzResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"build":{"type":"object"}},"required":["status"]},"PublicCatalog":{"type":"object","properties":{"product":{"type":"string"},"whenToUse":{"type":"string"},"freeTier":{"type":"string"},"links":{"type":"object"},"scopes":{"type":"object"}},"required":["product","links"]},"PublicProduct":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"audience":{"type":"string"},"whenToUse":{"type":"string"},"contact":{"type":"object"}},"required":["name","description"]},"SampleBusiness":{"type":"object","properties":{"sample":{"type":"boolean","const":true},"business":{"type":"object","properties":{"name":{"type":"string"},"industry":{"type":"string"},"location":{"type":"string"},"revenueUsd":{"type":"integer"}},"required":["name","industry"]}},"required":["sample","business"]},"SandboxTokenRequest":{"type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"scope":{"type":"string","example":"read:public"}}},"SandboxToken":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"bearer"},"scope":{"type":"string","example":"read:public"},"expires_in":{"type":"integer"}},"required":["access_token","token_type","scope"]},"OpenApiDocument":{"type":"object","properties":{"openapi":{"type":"string","example":"3.1.0"},"info":{"type":"object"},"paths":{"type":"object"},"components":{"type":"object"}},"required":["openapi","info","paths"]},"OpenApiYaml":{"type":"string","contentMediaType":"application/yaml","description":"OpenAPI 3.1 document serialized as YAML."},"JsonRpcRequest":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"]},"JsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":{"type":"object"},"error":{"type":"object"}},"required":["jsonrpc"]},"QuizQuestions":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object"}}}},"McpEventStream":{"type":"string","contentMediaType":"text/event-stream","description":"Server-sent events carrying JSON-RPC MCP messages."}}}}