Luna Insights API

openapi: 3.2.0
info:
  title: Luna Insights API
  description: 'Luna is a baby tracker for feeds, sleep, nappies, solids and routines, shared between parents and invited caregivers.


    This REST API is the same one the Luna web app uses. Every request is scoped to **one family**: the family is resolved from the bearer token (or session cookie) and there is no way to address another family''s data.


    ## Authentication


    * **Bearer token** (`Authorization: Bearer `), the way agents and scripts should call the API. Create one in the app (Settings → Connect an assistant) or `POST /api/vega/token` from a signed-in session. Tokens are stored hashed and can carry `read` or `read`+`write` scopes. A `read` token may call every `GET` (and `HEAD`) route plus `POST /api/ask` (asking only; a `remember:` question saves a note and needs `write`). Any other `POST`, `PUT`, `PATCH` or `DELETE` with a token that lacks `write` returns `403 {"error": "insufficient_scope", "required_scope": "write"}`. Each operation''s `x-required-scope` says which it needs.

    * **Session cookie** (`luna_session`), what the browser uses after `POST /login` or `POST /api/vega/onboard`.


    Only `GET /api/health` and `POST /api/vega/onboard` are reachable without credentials. Unauthenticated calls to anything else return `401 {"error": "unauthorized"}`.


    ## Conventions


    * Timestamps are ISO 8601 in the family''s local time (`YYYY-MM-DDTHH:MM:SS`); omit `ts` to log "now". Future timestamps are rejected.

    * Volumes are millilitres, weights kilograms, lengths centimetres. Families with `units: imperial` still store metric.

    * Errors are JSON `{"error": ""}` with a 4xx status.

    * Luna is not a medical device: nothing here diagnoses, assesses symptoms or advises on medication.


    ## Other ways in


    * **MCP connector** at `https://getmyluna.app/mcp` (streamable HTTP; OAuth sign-in, or the same bearer token): 23 tools, resources and prompts for Meta Muse, Claude Code and any MCP client. Manifest: `/.well-known/luna-connector.json`.

    * **Agent instructions**: `/llms.txt`. **Developer portal**: `/developers`. **CLI**: `/cli/luna.py`.'
  termsOfService: https://getmyluna.app/terms
  contact:
    name: Luna support
    url: https://getmyluna.app/contact
    email: hello@getmyluna.app
  version: 1.1.0
servers:
- url: https://getmyluna.app
  description: Production
tags:
- name: Insights
  description: Live state, patterns, weekly nutrition/allergen records and growth measurements derived from the log.
paths:
  /api/vega/live:
    get:
      tags:
      - Insights
      summary: Live status
      description: 'Asleep/awake, hunger state, next feed estimate, last nappy, today''s totals and any alert: derived from the log right now. `checklist` is the Getting started state from the server: `first_log`, `partner_joined`, `invite_sent`, `installed`.'
      operationId: live_status
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStatus'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/vega/away/seen:
    post:
      tags:
      - Insights
      summary: Mark away card seen
      description: Stores this user's last-seen timestamp so the While you were away card can clear.
      operationId: away_seen
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`insufficient_scope`: the bearer token lacks the `write` scope'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: write
  /api/vega/nudge/snooze:
    post:
      tags:
      - Insights
      summary: Snooze the in-app top nudge
      description: 'Hides the hero nudge card until the end of the family-local day. Body: `{id}` from `top_nudge`. Connector get_nudges is unchanged.'
      operationId: nudge_snooze
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NudgeSnoozeRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NudgeSnoozeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`insufficient_scope`: the bearer token lacks the `write` scope'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: write
  /api/vega/weekly-summary:
    get:
      tags:
      - Insights
      summary: Your week summary card
      description: 'The previous full ISO week (Monday to Sunday, family-local) from the family''s own log: feeds and nappies per day with entries, sleep logged per day (if any), entries per caregiver and days with entries out of 7. `show` is false (with a `reason`) while expecting, without a date of birth, for families under 7 days old, when that week has entries on fewer than 2 days, or once this caregiver has dismissed it this week.'
      operationId: weekly_summary
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklySummaryResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/vega/weekly-summary/seen:
    post:
      tags:
      - Insights
      summary: Dismiss the week summary card
      description: 'Hides the week summary card for this caregiver until the next ISO week. The body is optional: `week` is the ISO week the card was shown in. Only the current week or the one before is accepted; anything else, or no body, means the current week.'
      operationId: weekly_summary_seen
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeeklySummarySeenRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklySummarySeenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`insufficient_scope`: the bearer token lacks the `write` scope'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: write
  /api/vega/stats:
    get:
      tags:
      - Insights
      summary: Historical stats (legacy)
      description: Always `{}` for public families; kept for compatibility with older clients.
      operationId: stats
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/vega/patterns:
    get:
      tags:
      - Insights
      summary: Patterns and weekly review
      description: Sleep patterns, 14-day totals, today's events, and, once solids have started, 7-day nutrient tallies, targets and the allergen grid.
      operationId: patterns
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatternsResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/vega/measurements:
    get:
      tags:
      - Insights
      summary: Growth measurements
      description: All logged weight and length events, oldest first.
      operationId: measurements
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementsResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
components:
  schemas:
    WeeklySummaryAuthor:
      properties:
        author:
          type: string
          title: Author
          description: Display name (never the raw username). 'Other' for entries by no current member.
        entries:
          type: integer
          title: Entries
        is_me:
          type: boolean
          title: Is Me
      type: object
      required:
      - author
      - entries
      - is_me
      title: WeeklySummaryAuthor
    WeeklySummary:
      properties:
        week:
          type: string
          title: Week
          description: ISO week summarised (the previous one).
          examples:
          - 2026-W42
        week_start:
          type: string
          title: Week Start
          examples:
          - '2026-10-12'
        week_end:
          type: string
          title: Week End
          examples:
          - '2026-10-18'
        current_week:
          type: string
          title: Current Week
          examples:
          - 2026-W43
        days_logged:
          type: integer
          title: Days Logged
          description: Days of that week with at least one entry (out of 7).
        days_in_week:
          type: integer
          title: Days In Week
          default: 7
        entries:
          type: integer
          title: Entries
        feeds:
          type: integer
          title: Feeds
        nappies:
          type: integer
          title: Nappies
        feeds_per_day:
          type: number
          title: Feeds Per Day
          description: Feeds per day with entries.
        nappies_per_day:
          type: number
          title: Nappies Per Day
          description: Nappies per day with entries.
        sleep_logged:
          type: boolean
          title: Sleep Logged
        sleep_minutes_per_day:
          anyOf:
          - type: integer
          - type: 'null'
          title: Sleep Minutes Per Day
          description: Sleep logged per day with entries, in whole minutes. Null if no sleep was logged.
        by_author:
          items:
            $ref: '#/components/schemas/WeeklySummaryAuthor'
          type: array
          title: By Author
        baby_name:
          type: string
          title: Baby Name
      type: object
      required:
      - week
      - week_start
      - week_end
      - current_week
      - days_logged
      - entries
      - feeds
      - nappies
      - feeds_per_day
      - nappies_per_day
      - sleep_logged
      - by_author
      - baby_name
      title: WeeklySummary
      description: Counts from the family's own log for the previous full ISO week. No targets or comparisons.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WeeklySummarySeenResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
        week:
          type: string
          title: Week
          examples:
          - 2026-W43
      type: object
      required:
      - week
      title: WeeklySummarySeenResponse
    WeeklySummarySeenRequest:
      description: Optional body for dismissing the week summary card.
      properties:
        week:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The ISO week the card was shown in. Only the current week or the one before is accepted; anything else means the current week.
          examples:
          - 2026-W43
          title: Week
      title: WeeklySummarySeenRequest
      type: object
    PatternsResponse:
      properties:
        patterns:
          additionalProperties: true
          type: object
          title: Patterns
        daily_totals:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Daily Totals
        today:
          items:
            $ref: '#/components/schemas/Event'
          type: array
          title: Today
        nutrients_7d:
          additionalProperties: true
          type: object
          title: Nutrients 7D
        nutrients_today:
          additionalProperties: true
          type: object
          title: Nutrients Today
        nutrient_targets:
          additionalProperties: true
          type: object
          title: Nutrient Targets
        allergens_today:
          additionalProperties: true
          type: object
          title: Allergens Today
        allergen_grid:
          additionalProperties: true
          type: object
          title: Allergen Grid
        baby_name:
          type: string
          title: Baby Name
        dob:
          type: string
          title: Dob
          description: YYYY-MM-DD, or empty while the family is expecting.
        age_months:
          anyOf:
          - type: number
          - type: 'null'
          title: Age Months
        age_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Age Display
        flags:
          additionalProperties: true
          type: object
          title: Flags
          examples:
          - solids_started: false
        expecting:
          anyOf:
          - $ref: '#/components/schemas/Expecting'
          - type: 'null'
      type: object
      required:
      - patterns
      - daily_totals
      - today
      - nutrients_7d
      - nutrients_today
      - nutrient_targets
      - allergens_today
      - allergen_grid
      - baby_name
      - dob
      - age_months
      - age_display
      - flags
      title: PatternsResponse
      description: Everything the dashboard renders. Solid-food blocks are empty until `flags.solids_started` is true.
    NudgeSnoozeResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
        id:
          type: string
          title: Id
        until:
          type: string
          title: Until
          description: Family-local end of day; the nudge stays hidden until then.
          examples:
          - '2026-11-07T23:59:59'
      type: object
      required:
      - id
      - until
      title: NudgeSnoozeResponse
    OkResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
          examples:
          - true
      type: object
      title: OkResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WeeklySummaryResponse:
      properties:
        show:
          type: boolean
          title: Show
        reason:
          anyOf:
          - type: string
            enum:
            - expecting
            - no_dob
            - family_too_new
            - too_few_days
            - dismissed
          - type: 'null'
          title: Reason
        week:
          type: string
          title: Week
          description: The current ISO week (family-local).
          examples:
          - 2026-W43
        summary:
          anyOf:
          - $ref: '#/components/schemas/WeeklySummary'
          - type: 'null'
      type: object
      required:
      - show
      - week
      title: WeeklySummaryResponse
    Event:
      properties:
        id:
          type: string
          title: Id
          description: 8-hex-char id, unique within the family.
          examples:
          - af73aec9
        ts:
          type: string
          title: Ts
          description: ISO 8601 local timestamp.
          examples:
          - '2026-09-20T09:49:53'
        type:
          type: string
          enum:
          - milk
          - sleep
          - wake
          - nappy
          - poop
          - solid
          - note
          - supplement
          - weight
          - length
          title: Type
        author:
          type: string
          title: Author
          description: 'Who logged it: the caregiver''s first name, or `Family admin` / `Partner` until they''ve set one (`app`/`agent` for non-human). Never an email or username.'
          default: app
        author_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Author Name
          description: Same as `author` (display name).
        author_is_me:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Author Is Me
          description: 'Web session/token only: true when the current caregiver logged it.'
        ml:
          anyOf:
          - type: integer
            maximum: 500.0
            minimum: 0.0
          - type: 'null'
          title: Ml
          description: '`milk` only: millilitres (0 for a breastfeed).'
        kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Kind
          description: '`nappy`: wet|dirty|both|dry. `supplement`: vitd|iron|multivitamin.'
        foods:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Foods
          description: '`solid` only: what was eaten.'
        meal_type:
          anyOf:
          - type: string
            enum:
            - meal
            - snack
          - type: 'null'
          title: Meal Type
          description: '`solid` only.'
        kg:
          anyOf:
          - type: number
          - type: 'null'
          title: Kg
          description: '`weight` only.'
        cm:
          anyOf:
          - type: number
          - type: 'null'
          title: Cm
          description: '`length` only.'
        ug:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ug
          description: '`supplement` only: micrograms.'
        note:
          anyOf:
          - type: string
            maxLength: 300
          - type: 'null'
          title: Note
        reactions:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Reactions
          description: 'Emoji reactions from caregivers: `emoji`, `ts`, `user` (display name), `mine`.'
      type: object
      required:
      - id
      - ts
      - type
      title: Event
      description: One logged event. Fields beyond `id`/`ts`/`type`/`author` depend on `type`.
    MeasurementsResponse:
      properties:
        measurements:
          items:
            $ref: '#/components/schemas/Event'
          type: array
          title: Measurements
          description: '`weight` and `length` events, oldest first.'
      type: object
      required:
      - measurements
      title: MeasurementsResponse
    LiveStatus:
      properties:
        now:
          type: string
          title: Now
        asleep:
          type: boolean
          title: Asleep
        night_sleep:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Night Sleep
        awake_minutes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Awake Minutes
        alert_level:
          anyOf:
          - type: string
          - type: 'null'
          title: Alert Level
        alert_msg:
          anyOf:
          - type: string
          - type: 'null'
          title: Alert Msg
        hungry_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Hungry State
          description: e.g. `not_yet`, `hungry_soon`, `overdue`, `dream_feed`, `unknown`.
        next_feed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Feed At
        last_milk_ml:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Milk Ml
        ml_today:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ml Today
        feeds_today:
          anyOf:
          - type: integer
          - type: 'null'
          title: Feeds Today
        last_poop_hours_ago:
          anyOf:
          - type: number
          - type: 'null'
          title: Last Poop Hours Ago
        poop_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Poop Status
        expected_bedtime_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expected Bedtime At
        next_nap_window_at:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Next Nap Window At
        daily_milk_target_ml:
          anyOf:
          - type: integer
          - type: 'null'
          title: Daily Milk Target Ml
        supplement_log:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Supplement Log
        age_months:
          anyOf:
          - type: number
          - type: 'null'
          title: Age Months
          description: Null while the family is expecting.
        expecting:
          anyOf:
          - $ref: '#/components/schemas/Expecting'
          - type: 'null'
          description: Set while the baby isn't born yet.
      type: object
      required:
      - now
      - asleep
      title: LiveStatus
      description: Current state derived from the log. Additional keys may appear; the ones below are stable.
    Expecting:
      properties:
        due_date:
          type: string
          title: Due Date
          examples:
          - '2027-03-12'
        days_until_due:
          type: integer
          title: Days Until Due
          description: 0 once the due date arrives.
        due_date_reached:
          type: boolean
          title: Due Date Reached
        days_overdue:
          type: integer
          title: Days Overdue
          description: Days since the due date while the birth isn't confirmed yet (0 before it). The family stays expecting until a caregiver confirms the arrival.
          default: 0
      type: object
      required:
      - due_date
      - days_until_due
      - due_date_reached
      title: Expecting
      description: 'Set while the baby isn''t born yet: there is no age and no age-based target.'
    NudgeSnoozeRequest:
      description: Dismiss the in-app top nudge until the end of the family-local day.
      properties:
        id:
          description: The `id` from `top_nudge` on GET /api/vega/live.
          examples:
          - a1b2c3d4e5f6
          title: Id
          type: string
      required:
      - id
      title: NudgeSnoozeRequest
      type: object
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Machine-readable code (e.g. `unauthorized`, `not_found`) or a short message.
          examples:
          - unauthorized
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Optional human-readable detail.
      type: object
      required:
      - error
      title: ErrorResponse
      description: Every error is a JSON object with an `error` code or message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'Token from Settings → Connect an assistant or `POST /api/vega/token`. Scopes: `read`, `write`. A `read` token gets `403 insufficient_scope` on any operation whose `x-required-scope` is `write`.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: luna_session
      description: Browser session set by `POST /login` or `POST /api/vega/onboard`.
externalDocs:
  description: Developer portal
  url: https://getmyluna.app/developers