Fluid Recall Tokens API

openapi: 3.2.0
info:
  title: Fluid Recall Tokens 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: Tokens
paths:
  /tokens:
    get:
      operationId: listTokens
      summary: List token metadata
      description: Routine read. Returns token ids, labels, and timestamps. Does not return the token value or its hash.
      x-muse-action-class: read
      responses:
        '200':
          description: Tokens for this bearer.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Tokens
    post:
      operationId: mintToken
      summary: Mint an additional token
      description: Write. Returns another personal token. The bearer that called this stays valid. Save the new token for API calls.
      x-muse-action-class: write
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                label:
                  type:
                  - string
                  - 'null'
                  maxLength: 80
      responses:
        '201':
          description: The new one-time token.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Tokens
  /tokens/rotate:
    post:
      operationId: rotateToken
      summary: Rotate the current token
      description: Write. Revokes the bearer that called this and returns a replacement token. Save the new token for API calls. The previous token's next call is 401.
      x-muse-action-class: write
      responses:
        '200':
          description: The replacement one-time token.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Tokens
  /tokens/revoke:
    post:
      operationId: revokeToken
      summary: Revoke the current token
      description: Write. Revokes the bearer that called this. The next call with that token is 401.
      x-muse-action-class: write
      responses:
        '200':
          description: The token is revoked.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or wrong token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Tokens
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.'