Luna Ask Luna API

openapi: 3.2.0
info:
  title: Ask Luna 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: Ask Luna
  description: Luna Plus AI summaries grounded in the family's own log, plus the notes Luna remembers.
paths:
  /api/ask:
    post:
      tags:
      - Ask Luna
      summary: Ask Luna (Luna Plus)
      description: A question answered from this family's own log, in Luna's non-clinical lane. Requires Luna Plus (`402 payment_required` otherwise) and is subject to daily/monthly limits (`429 usage_limit_reached`). Prefix the question with `remember:` to save a note instead. A `read` token may ask; saving a `remember:` note needs the `write` scope (`403 insufficient_scope` otherwise).
      operationId: ask_luna
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Luna Plus required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: One-time Ask Luna AI opt-in needed first (`ai_consent_required`); see `POST /api/consent`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Usage limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/ask/notes:
    get:
      tags:
      - Ask Luna
      summary: Notes Luna remembers
      description: Durable notes saved for this family.
      operationId: list_notes
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotesResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/ask/notes/delete:
    post:
      tags:
      - Ask Luna
      summary: Forget a note
      description: Delete one remembered note by its `ts`.
      operationId: delete_note
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteDeleteRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '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
components:
  schemas:
    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
    NotesResponse:
      properties:
        notes:
          items:
            $ref: '#/components/schemas/Note'
          type: array
          title: Notes
      type: object
      required:
      - notes
      title: NotesResponse
    Note:
      properties:
        ts:
          type: string
          title: Ts
        text:
          type: string
          title: Text
        tags:
          items:
            type: string
          type: array
          title: Tags
      type: object
      required:
      - ts
      - text
      title: Note
    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
    NoteDeleteRequest:
      properties:
        ts:
          description: The note's `ts`, which is its identifier.
          title: Ts
          type: string
      required:
      - ts
      title: NoteDeleteRequest
      type: object
    AskRequest:
      properties:
        question:
          description: Prefix with `remember:` to save a note instead of asking.
          examples:
          - How did feeding go this week?
          title: Question
          type: string
      required:
      - question
      title: AskRequest
      type: object
    AskResponse:
      properties:
        answer:
          type: string
          title: Answer
        reply:
          anyOf:
          - type: string
          - type: 'null'
          title: Reply
          description: Same as `answer` (legacy key).
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: '`null` when a guardrail answered without the model.'
        context_used:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Context Used
        guardrail:
          anyOf:
          - type: string
          - type: 'null'
          title: Guardrail
          examples:
          - clinical_escalation
        usage_limit:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Usage Limit
        saved_notes:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Saved Notes
      type: object
      required:
      - answer
      title: AskResponse
    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