Fluid Recall Export API

openapi: 3.2.0
info:
  title: Fluid Recall Export 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: Export
paths:
  /export/manifest:
    get:
      operationId: exportManifest
      summary: List what this token can export
      description: 'Important read for off-boarding. Returns the resource catalog, row counts, pagination limits, and completeness rules for this bearer only. Does not include answers or other tenants. The break-glass operator secret cannot call this. A complete off-board is this tenant only: account metadata, study settings, token metadata, decks, every card page (answers, retired cards, and embedded schedules), and every review page. Start with GET /api/v1/export. When complete is true, stop. When it is false, follow cards.nextCursor with resource=cards and reviews.nextCursor with resource=reviews until each is null. Manifest counts must match the union of items. Rate-limit buckets and operator counters are not tenant data. Token plaintext and tokenHash are never exported.'
      x-muse-action-class: important-read
      responses:
        '200':
          description: Export catalog for this token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportManifest'
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No account for this token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Export
  /export:
    get:
      operationId: exportSnapshot
      summary: Dump this token's studying records
      description: 'Important read for off-boarding and migration. Returns this bearer''s account metadata, settings, token metadata, decks, cards with answers and schedules (including retired), and review history. Never includes another tenant. Token plaintext and tokenHash are omitted. Rate-limit buckets and operator counters are omitted. limit defaults to 200 and maxes at 500. When complete is false, call again with resource=cards or resource=reviews and the matching nextCursor. This is not a drill reveal. During a study session still use revealCard for one answer. A complete off-board is this tenant only: account metadata, study settings, token metadata, decks, every card page (answers, retired cards, and embedded schedules), and every review page. Start with GET /api/v1/export. When complete is true, stop. When it is false, follow cards.nextCursor with resource=cards and reviews.nextCursor with resource=reviews until each is null. Manifest counts must match the union of items. Rate-limit buckets and operator counters are not tenant data. Token plaintext and tokenHash are never exported.'
      x-muse-action-class: important-read
      parameters:
      - name: resource
        in: query
        required: false
        schema:
          type: string
          enum:
          - cards
          - reviews
        description: Omit on the first call to receive account, settings, tokens, decks, and the first card and review pages. Use cards or reviews to continue a page.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 200
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Page token from cards.nextCursor or reviews.nextCursor. Prefix is cards.v1. or reviews.v1.
      responses:
        '200':
          description: Tenant-scoped studying dump.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportSnapshot'
        '400':
          description: Invalid resource, limit, or cursor.
          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 account for this token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Export
components:
  schemas:
    ExportManifest:
      type: object
      additionalProperties: false
      required:
      - format
      - generatedAt
      - account
      - resources
      - omitted
      - page
      - completeness
      properties:
        format:
          type: string
          const: fluid-recall.export.v1
        generatedAt:
          type: string
          description: UTC ISO-8601 timestamp ending in Z
        account:
          type: object
        resources:
          type: array
          items:
            type: object
        omitted:
          type: array
          items:
            type: object
        page:
          type: object
          additionalProperties: false
          required:
          - defaultLimit
          - maxLimit
          properties:
            defaultLimit:
              type: integer
              const: 200
            maxLimit:
              type: integer
              const: 500
        completeness:
          type: string
    ExportSnapshot:
      type: object
      additionalProperties: false
      required:
      - format
      - exportedAt
      - complete
      - resource
      - account
      - settings
      - tokens
      - decks
      - cards
      - reviews
      - counts
      - completeness
      properties:
        format:
          type: string
          const: fluid-recall.export.v1
        exportedAt:
          type: string
          description: UTC ISO-8601 timestamp ending in Z
        complete:
          type: boolean
          description: True when this first snapshot already contains every card and review. Follow nextCursor when false.
        resource:
          type: string
          enum:
          - all
          - cards
          - reviews
        account:
          type: object
        settings:
          type:
          - object
          - 'null'
        tokens:
          type: array
          description: Metadata only. Never plaintext or tokenHash.
        decks:
          type: array
        cards:
          type: object
        reviews:
          type: object
        counts:
          type: object
        completeness:
          type: string
    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.'