Luna Tokens API

openapi: 3.2.0
info:
  title: Luna Tokens 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: Tokens
  description: Bearer tokens for agents, scripts and the MCP connector.
paths:
  /api/vega/token:
    post:
      tags:
      - Tokens
      summary: Create a bearer token
      description: Mints a token for agents, scripts or the MCP connector. The plaintext is returned **once**. Re-minting with the same `label` replaces that token; different labels coexist. Optional body, omit it for a full-access token labelled with your username.
      operationId: create_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '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/tokens:
    get:
      tags:
      - Tokens
      summary: List tokens
      description: Every token issued for this family (never the secret).
      operationId: list_tokens
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
      - sessionCookie: []
      x-required-scope: read
  /api/vega/token/revoke:
    post:
      tags:
      - Tokens
      summary: Revoke a token
      description: Immediately stops that token (and any assistant using it).
      operationId: revoke_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRevokeRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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
    TokenRevokeRequest:
      properties:
        id:
          description: Token id from `GET /api/vega/tokens`.
          title: Id
          type: string
      required:
      - id
      title: TokenRevokeRequest
      type: object
    OkResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
          examples:
          - true
      type: object
      title: OkResponse
    TokenInfo:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        username:
          type: string
          title: Username
        scopes:
          items:
            type: string
          type: array
          title: Scopes
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - label
      - username
      - scopes
      - created_at
      title: TokenInfo
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TokensResponse:
      properties:
        tokens:
          items:
            $ref: '#/components/schemas/TokenInfo'
          type: array
          title: Tokens
      type: object
      required:
      - tokens
      title: TokensResponse
    TokenResponse:
      properties:
        token:
          type: string
          title: Token
          description: Shown once; store it securely.
        luna_url:
          type: string
          title: Luna Url
        mcp_url:
          type: string
          title: Mcp Url
          examples:
          - https://getmyluna.app/mcp
        label:
          type: string
          title: Label
        scopes:
          items:
            type: string
          type: array
          title: Scopes
      type: object
      required:
      - token
      - luna_url
      - mcp_url
      - label
      - scopes
      title: TokenResponse
    TokenRequest:
      properties:
        label:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Re-minting the same label replaces that token. Defaults to your username.
          examples:
          - Muse
          title: Label
        scopes:
          anyOf:
          - items:
              enum:
              - read
              - write
              type: string
            type: array
          - type: 'null'
          default: null
          description: 'Default: both.'
          examples:
          - - read
            - write
          title: Scopes
      title: TokenRequest
      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