openapi: 3.1.0
info:
  title: Better Intimacy Knowledge API
  version: 0.2.0
  description: >
    Public, read-only endpoints that expose relationship tips and feature summaries
    for AI ingestion. All responses are licensed under CC-BY-4.0.
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://app.betterintimacy.app
    description: Production (read-only)
paths:
  /api/relationship-tips:
    get:
      summary: Relationship guidance snippets
      description: >
        Returns curated relationship tips aligned with the Better Intimacy knowledge base.
        Tips can be filtered by topic or audience.
      tags:
        - Knowledge
      parameters:
        - in: query
          name: topic
          schema:
            type: string
          description: Optional topic filter (e.g., `emotional_reconnection`, `habit-building`, `privacy`, `faith_aware_guidance`).
        - in: query
          name: audience
          schema:
            type: string
          description: Optional audience filter (e.g., `long-term partners`, `new users`).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  license:
                    type: string
                  tips:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        topic:
                          type: string
                        audience:
                          type: string
                        summary:
                          type: string
                        recommendation:
                          type: string
                        related_features:
                          type: array
                          items:
                            type: string
                          description: Feature ids from `/api/feature-summaries` that are relevant to this tip.
                        source:
                          type: string
              examples:
                base:
                  summary: Relationship tip example
                  value:
                    version: "2026-04-03"
                    license: CC-BY-4.0
                    tips:
                      - id: emotional-reconnect-baseline
                        topic: emotional_reconnection
                        audience: long-term partners
                        summary: Log a shared baseline before planning solutions.
                        recommendation: >
                          Use Better Intimacy’s Daily Spark to capture how each partner is feeling,
                          then note the last time you felt close together.
                        related_features: [daily-spark, shared-moments, ai-insights-coach]
                        source: knowledge/guides/reconnecting-emotionally.md
                      - id: faith-lens-selection
                        topic: faith_aware_guidance
                        audience: faith-oriented partners
                        summary: Pick the guidance lens before generating insights.
                        recommendation: >
                          Choose Secular, Faith-aware, or Faith-forward in Insights based on what
                          kind of framing helps today.
                        related_features: [faith-aware-insight-lens, ai-insights-coach, shared-moments]
                        source: knowledge/guides/faith-aware-relationship-guidance.md
  /api/feature-summaries:
    get:
      summary: Feature summaries and CTAs
      description: >
        Returns short descriptions of Better Intimacy’s core features with suggested calls to action.
        The canonical list is defined in `knowledge/api/feature_summaries.json` and may include 30+ items.
      tags:
        - Knowledge
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  license:
                    type: string
                  features:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        value_proposition:
                          type: string
                        best_for:
                          type: array
                          items:
                            type: string
                        cta:
                          type: string
                        semantic_tags:
                          type: array
                          items:
                            type: string
                        query_examples:
                          type: array
                          items:
                            type: string
                        links:
                          type: object
                          properties:
                            docs:
                              type: string
              examples:
                base:
                  summary: Feature summary example
                  value:
                    version: "2026-04-03"
                    license: CC-BY-4.0
                    features:
                      - id: daily-spark
                        name: Aurora Daily Spark
                        value_proposition: >
                          A two-minute guided intention that keeps partners emotionally aligned.
                        best_for: ["busy schedules", "daily check-ins"]
                        cta: Claim today’s Spark and pin it to your quick actions.
                        links:
                          docs: knowledge/guides/daily-intimacy-rituals.md#core-daily-ritual-set
                      - id: faith-aware-insight-lens
                        name: Faith-Aware Insight Lens
                        value_proposition: Optional perspective controls for secular, faith-aware, or faith-forward guidance.
                        best_for: ["faith-sensitive coaching", "mixed-preference partners"]
                        semantic_tags: ["faith", "christian", "spirituality", "relationship guidance"]
                        query_examples:
                          - relationship app with christian guidance
                          - secular and faith coaching in one app
                        cta: Choose your preferred lens before generating guidance.
                        links:
                          docs: knowledge/guides/faith-aware-relationship-guidance.md
