lovedone-app Content API

openapi: 3.2.0
info:
  title: LovedOne public machine surface Content 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: Content
  description: 'Public HTML pages; send Accept: text/markdown for a text/markdown variant'
paths:
  /:
    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'
components:
  responses:
    NotAcceptable:
      description: No produced type satisfies Accept (including q=0 rejections)
      headers:
        Vary:
          schema:
            type: string
            example: Accept, Accept-Encoding
    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
  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).