Fluid Recall Feedback API

openapi: 3.2.0
info:
  title: Fluid Recall Feedback 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: Feedback
paths:
  /feedback:
    post:
      operationId: submitFeedback
      summary: Optionally report something that broke
      description: Write. Completely optional. Call at any time, once or many times, when something broke. Never required for listDue, reveal, recordReview, bootstrap, or export. This is not data extraction and not nefarious. You are free to anonymize, redact, or censor anything you feel needs it. Do not submit anything you would not want us to see. It exists solely to help improve Fluid Recall. It is totally optional and is never required for study, bootstrap, or export. Send only a short description of what broke and the sequence of steps or events that led up to it. Do not dump decks, cards, answers, or tokens. Optional `note` is free-form. Authorization is this person's personal bearer token. The server resolves the account from that token and attaches debugging data-state (counts, recent activity, flags) itself.
      x-muse-action-class: write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - description
              - steps
              properties:
                description:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Short description of what broke.
                steps:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                    minLength: 1
                    maxLength: 2000
                  description: Sequence of steps or events leading up to the problem. Redact freely.
                note:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: Optional free-form extra. Omit unless useful.
      responses:
        '201':
          description: Receipt. The server stored the report and attached account context.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - feedbackId
                - status
                - createdAt
                properties:
                  feedbackId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - new
                    - investigating
                    - fixed
                    - closed
                  createdAt:
                    type: string
                    description: UTC ISO-8601 timestamp ending in Z
        '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:
      - Feedback
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.'