Fluid Recall Settings API

openapi: 3.2.0
info:
  title: Fluid Recall Settings API
  version: 0.0.0
  description: 'System of record for spaced recall. One service with four doors: MCP at POST /mcp (also /api/mcp), Markdown /api/v1/agent and /api/v1/dev, and JSON /api/v1. Agents may use whatever works best. None is deprecated. JSON operations sit at the /api/v1 root (/due, /decks, /reviews). Request bodies are JSON. Markdown responses use Content-Type text/plain; the body is Markdown. MCP is stateless Streamable HTTP. Send Authorization: Bearer . No Mcp-Session-Id. The same MCP door speaks the ChatGPT MCP Events subset (events/list, events/subscribe, events/unsubscribe) with webhook-only delivery. Muse bootstraps a personal API token with POST /accounts or POST /bootstrap and keeps drilling. The bearer token is the tenant. This API decides what is due and when it is due next. Bootstrap, reviews, and unauthenticated reads are rate limited. HTTP 429 is retryable. ---'
servers:
- url: /api/v1
security:
- bearerAuth: []
- poppyDpop: []
tags:
- name: Settings
paths:
  /settings:
    get:
      operationId: getStudySettings
      summary: Read the new-card allowance
      description: 'Routine read. Account newCardsPerDay, IANA timezone (UTC until changed), and dayBoundaryHour (4 until changed, meaning 04:00 local). newCardsPerDay here is the fallback for a deck whose own field is null. A fresh account may show 20 because that column default is a legacy fallback, not a number you chose for a deck. Choose newCardsPerDay with the person for this deck. There is no default of 20. When they have a deadline, call previewDeadlinePlan first: it returns ceil(remaining new cards / study days) as a floor. Weigh study time (more time, a higher number), that deadline floor, and card complexity (tiny facts such as times tables can be higher; a beefy card such as the five steps of a cycle must be lower). You may raise N above the floor or negotiate more study time. Send that integer. After bulk card adds, re-run previewDeadlinePlan with that deckId and consider applyDeadlinePlan or updateDeck. 0 introduces no new cards unless the caller asks for extras.'
      x-muse-action-class: read
      responses:
        '200':
          description: The account study settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudySettings'
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Settings
    patch:
      operationId: updateStudySettings
      summary: Change the new-card allowance
      description: Write. Send newCardsPerDay, timezone, dayBoundaryHour, or any combination. newCardsPerDay here changes the fallback for decks that still have null. Decks that store their own integer keep it. Prefer updateDeck when you are changing the deck you are coaching. This does not reset cards already introduced today. To study past today's cap without changing the stored number, use listDue with newCardMode=extra.
      x-muse-action-class: write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                newCardsPerDay:
                  type: integer
                  minimum: 0
                  maximum: 9999
                timezone:
                  type: string
                dayBoundaryHour:
                  type: integer
                  minimum: 0
                  maximum: 23
      responses:
        '200':
          description: The updated account study settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudySettings'
        '400':
          description: Invalid body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Settings
components:
  schemas:
    StudySettings:
      type: object
      additionalProperties: false
      required:
      - newCardsPerDay
      - timezone
      - dayBoundaryHour
      properties:
        newCardsPerDay:
          type: integer
          minimum: 0
          maximum: 9999
          description: Account fallback used only when a deck's newCardsPerDay is null. A stored 20 on a new account is the legacy column default, not a coaching choice. Set the deck explicitly.
        timezone:
          type: string
          description: IANA timezone for the study day. UTC unless changed.
        dayBoundaryHour:
          type: integer
          minimum: 0
          maximum: 23
          description: Local hour when the study day starts. 4 means 04:00. Before that hour, the previous study day is still in effect.
    Error:
      type: object
      additionalProperties: false
      required:
      - code
      - message
      - retryable
      properties:
        code:
          type: string
          enum:
          - BAD_REQUEST
          - UNAUTHORIZED
          - FORBIDDEN
          - NOT_FOUND
          - CONFLICT
          - UNAVAILABLE
          - RATE_LIMITED
        message:
          type: string
        retryable:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal Fluid Recall API token from POST /accounts (or POST /bootstrap). Save it for API calls. The operator break-glass secret is a different credential and cannot call drill operations.
    poppyDpop:
      type: http
      scheme: DPoP
      description: 'Personal Agent Protocol (Poppy v0.1) Session Token from POST https://fluidrecall.com/oauth/token, sent as Authorization: DPoP <token> with a DPoP proof header on every call. poppy:read allows reads and poppy:write allows changes; personal API token management is not available. See https://fluidrecall.com/.well-known/poppy.json and https://fluidrecall.com/docs/personal-agent-protocol.'