lovedone-app Discovery API

openapi: 3.2.0
info:
  title: LovedOne public machine surface Discovery API
  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.


    Do 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.


    Public 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
security: []
tags:
- name: Discovery
  description: Unauthenticated machine-readable files on lovedone.app
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
components:
  responses:
    JsonError:
      description: Structured JSON error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  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
  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).