{
  "openapi": "3.0.3",
  "info": {
    "title": "LovedOne public machine surface",
    "version": "1.0.0",
    "description": "lovedone.app is a static consumer landing site (no private product CRUD). This document describes the public discovery files hosted here and the real authenticated Loved One family-inbox APIs hosted on inbox.lovedone.app / api.lovedone.app.\n\nDo not expect REST resources for messages or loved ones on this host. Family data is reached through the Model Context Protocol (JSON-RPC over Streamable HTTP) after the user mints a key or completes OAuth.\n\nPublic pages on this host also negotiate `Accept: text/markdown` (acceptmarkdown.com).",
    "contact": {
      "name": "Terahertz, Inc. dba LovedOne",
      "email": "hello@lovedone.app",
      "url": "https://lovedone.app"
    },
    "license": {
      "name": "Proprietary — see Terms",
      "url": "https://lovedone.app/terms"
    }
  },
  "servers": [
    {
      "url": "https://lovedone.app",
      "description": "Marketing site and public discovery (this spec's default server)"
    },
    {
      "url": "https://api.lovedone.app",
      "description": "Authenticated MCP (JSON-RPC). Not a REST CRUD API."
    },
    {
      "url": "https://inbox.lovedone.app",
      "description": "Signed-in family inbox application"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Unauthenticated machine-readable files on lovedone.app"
    },
    {
      "name": "Content",
      "description": "Public HTML pages; send Accept: text/markdown for a text/markdown variant"
    },
    {
      "name": "MCP",
      "description": "Authenticated family-inbox Model Context Protocol (hosted off this landing origin)"
    }
  ],
  "security": [],
  "paths": {
    "/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "This OpenAPI document",
        "operationId": "getOpenApi",
        "responses": {
          "200": {
            "description": "OpenAPI 3.0 specification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "405": { "$ref": "#/components/responses/JsonError" },
          "500": { "$ref": "#/components/responses/JsonError" }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "OpenAPI document (API alias)",
        "operationId": "getOpenApiAlias",
        "responses": {
          "200": {
            "description": "Same document as /openapi.json",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/JsonError" },
          "405": { "$ref": "#/components/responses/JsonError" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "LLM / agent index",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "Plain-text agent index",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "XML sitemap of public pages",
        "operationId": "getSitemap",
        "responses": {
          "200": {
            "description": "Sitemap",
            "content": {
              "application/xml": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Robots exclusion file",
        "operationId": "getRobots",
        "responses": {
          "200": {
            "description": "robots.txt",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp/server.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "MCP server manifest for app.lovedone/family-inbox",
        "operationId": "getMcpManifest",
        "responses": {
          "200": {
            "description": "MCP server metadata (canonical endpoint is api.lovedone.app/mcp/v1)",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": ["Content"],
        "summary": "LovedOne homepage",
        "operationId": "getHome",
        "parameters": [
          { "$ref": "#/components/parameters/Accept" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/about": {
      "get": {
        "tags": ["Content"],
        "summary": "About LovedOne",
        "operationId": "getAbout",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/our-brands": {
      "get": {
        "tags": ["Content"],
        "summary": "Our brands",
        "operationId": "getOurBrands",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/getting-started": {
      "get": {
        "tags": ["Content"],
        "summary": "Setup guide",
        "operationId": "getGettingStarted",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/for-providers": {
      "get": {
        "tags": ["Content"],
        "summary": "Provider brief",
        "operationId": "getForProviders",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/blog": {
      "get": {
        "tags": ["Content"],
        "summary": "Blog index",
        "operationId": "getBlog",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/privacy": {
      "get": {
        "tags": ["Content"],
        "summary": "Privacy policy",
        "operationId": "getPrivacy",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/terms": {
      "get": {
        "tags": ["Content"],
        "summary": "Terms of service",
        "operationId": "getTerms",
        "parameters": [{ "$ref": "#/components/parameters/Accept" }],
        "responses": {
          "200": { "$ref": "#/components/responses/NegotiatedPage" },
          "406": { "$ref": "#/components/responses/NotAcceptable" }
        }
      }
    },
    "/mcp/v1": {
      "servers": [{ "url": "https://api.lovedone.app" }],
      "get": {
        "tags": ["MCP"],
        "summary": "MCP liveness / tool listing (no secrets)",
        "operationId": "getMcpProbe",
        "description": "JSON metadata about the LovedOne MCP server. Tool calls require POST + credentials.",
        "responses": {
          "200": {
            "description": "Server metadata and tool list",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["MCP"],
        "summary": "MCP JSON-RPC (Streamable HTTP)",
        "operationId": "postMcp",
        "description": "Authenticated JSON-RPC methods: initialize, tools/list, tools/call, ping.\n\nLive auth: `Authorization: Bearer sk-sand-...` minted at https://inbox.lovedone.app/settings/mcp-keys, or OAuth 2.1 + PKCE. Phase 1 API keys are not scope-gated (empty scope list = full caller access). OAuth authorization-code scopes below are advertised at inbox.lovedone.app/.well-known/oauth-authorization-server.\n\nTools and required scopes:\n- ping — no scope\n- get_user_profile — profile:read\n- list_loved_ones — care_circle:read\n- list_care_events — care_circle:read\n- invite_family_member — care_circle:write\n- create_provider_code — care_circle:write\n- reply_to_inbox_message — care_circle:write\n\nAlias: POST https://inbox.lovedone.app/api/mcp",
        "security": [
          { "LovedOneApiKey": [] },
          {
            "LovedOneOAuth": ["profile:read", "care_circle:read"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "id": {},
                  "method": {
                    "type": "string",
                    "enum": ["initialize", "tools/list", "tools/call", "ping"]
                  },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credentials. WWW-Authenticate points at RFC 9728 resource metadata.",
            "headers": {
              "WWW-Authenticate": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Accept": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "description": "Content negotiation (acceptmarkdown.com). text/markdown returns Markdown; text/html or */* returns the existing visual page. Responses include Vary: Accept, Accept-Encoding.",
        "schema": {
          "type": "string",
          "example": "text/markdown"
        }
      }
    },
    "securitySchemes": {
      "LovedOneApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk-sand-",
        "description": "LovedOne MCP API key minted by a signed-in family member at https://inbox.lovedone.app/settings/mcp-keys. Send `Authorization: Bearer sk-sand-...`. Phase 1 keys store a reserved `scopes` array; an empty list means full access for that caller (not anonymous public access). Keys never grant another family's workspace."
      },
      "LovedOneOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization-code + PKCE for MCP clients. Issuer https://inbox.lovedone.app. Metadata: https://inbox.lovedone.app/.well-known/oauth-authorization-server and https://inbox.lovedone.app/.well-known/oauth-protected-resource. Public scopes match packages/auth MCP_SCOPES (profile:read, care_circle:read, care_circle:write). audit:read exists in the schema but is not offered by default (public: false).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://inbox.lovedone.app/oauth/authorize",
            "tokenUrl": "https://inbox.lovedone.app/oauth/token",
            "refreshUrl": "https://inbox.lovedone.app/oauth/token",
            "scopes": {
              "profile:read": "See the caller's name, email, and LovedOne workspace membership. Required by get_user_profile.",
              "care_circle:read": "List loved ones and read recent care events. Required by list_loved_ones and list_care_events.",
              "care_circle:write": "Invite family, add providers, send replies, and add notes or visits on your behalf. Required by invite_family_member, create_provider_code, reply_to_inbox_message, add_visit_note, and schedule_visit.",
              "audit:read": "Read the caller's agent activity log (internal — not advertised on the authorization server by default)."
            }
          }
        }
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine code (not_found, method_not_allowed, not_acceptable, spec_unavailable, bad_request)"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation"
              },
              "hint": {
                "type": "string",
                "description": "What to try next"
              }
            }
          }
        }
      }
    },
    "responses": {
      "JsonError": {
        "description": "Structured JSON error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "NegotiatedPage": {
        "description": "HTML for browsers; Markdown when Accept prefers text/markdown",
        "headers": {
          "Vary": {
            "schema": { "type": "string", "example": "Accept, Accept-Encoding" }
          }
        },
        "content": {
          "text/html": { "schema": { "type": "string" } },
          "text/markdown": { "schema": { "type": "string" } }
        }
      },
      "NotAcceptable": {
        "description": "No produced type satisfies Accept (including q=0 rejections)",
        "headers": {
          "Vary": {
            "schema": { "type": "string", "example": "Accept, Accept-Encoding" }
          }
        }
      }
    }
  }
}