Fluid Recall Messages API

openapi: 3.2.0
info:
  title: Fluid Recall Messages 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: Messages
paths:
  /messages/{messageId}:
    get:
      operationId: getMailMessage
      summary: Read one owned message including the body
      description: Important read. Returns text and HTML for one message this token owns. Ask before opening mail the person did not request. Another token's message is 404.
      x-muse-action-class: important-read
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Full message. bodyIncluded is true.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No message with that id for this token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Messages
  /messages/{messageId}/reply:
    post:
      operationId: replyMailMessage
      summary: Reply to one owned message
      description: Write. Ask before sending. Recipients, In-Reply-To, References, and threadId come from the original message. Requires text and/or html.
      x-muse-action-class: write
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                text:
                  type: string
                  maxLength: 64000
                html:
                  type: string
                  maxLength: 128000
                subject:
                  type: string
                  minLength: 1
                  maxLength: 998
      responses:
        '201':
          description: Stored outbound reply.
          content:
            application/json:
              schema:
                type: object
        '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'
        '404':
          description: No message with that id for this token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Messages
components:
  schemas:
    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.'