openapi: 3.1.0
info:
  title: AI Insights for Humans
  version: 0.6.0
  description: A working notebook of practical AI interpretability, prompting, reliability, and tooling notes for people who want evidence instead of hype.
servers:
  - url: https://tips.platphormnews.com
paths:
  /api/health:
    get:
      summary: Public health summary
      responses:
        "200":
          description: Health payload
  /api/v1/health:
    get:
      summary: Versioned public health summary
      responses:
        "200":
          description: Health payload
  /api/v1/entries:
    get:
      summary: List notebook entries
      parameters:
        - in: query
          name: q
          schema:
            type: string
        - in: query
          name: kind
          schema:
            type: string
            enum: [all, tip, method, tool]
        - in: query
          name: tag
          schema:
            type: string
      responses:
        "200":
          description: Entry list
  /api/v1/focus-mode:
    get:
      summary: Read full-screen focus mode payload
      responses:
        "200":
          description: Focus frames and practice loop
  /api/v1/integrations:
    get:
      summary: Read Dictionary and Notes integration map
      responses:
        "200":
          description: Public-safe cross-site integration payload
  /api/v1/platform-literacy:
    get:
      summary: Read interactive PlatPhormNews root literacy tips
      responses:
        "200":
          description: Platform discovery, policy, MCP, JSON-LD, RSS, and safety tips
  /api/v1/research-trends:
    get:
      summary: Read source-backed AI research trends, demos, prompt contracts, and front-end roadmap
      responses:
        "200":
          description: Research trends, Loops, OpenClaw, Webhooks, AI mind, and cross-model prompt payload
  /api/v1/operator-patterns:
    get:
      summary: Read observable operator strengths, drag patterns, repair loops, and reusable prompts
      responses:
        "200":
          description: Public-safe workflow analysis of what this operator does well and where the style can drag
  /api/v1/entries/{id}:
    get:
      summary: Read one notebook entry
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Entry detail
        "404":
          description: Entry not found
  /api/v1/reports:
    post:
      summary: Generate a notebook/platform report
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: Generated report
        "401":
          description: PLATPHORM_API_KEY required
  /api/mcp:
    get:
      summary: MCP endpoint metadata
      responses:
        "200":
          description: MCP metadata
    post:
      summary: JSON-RPC 2.0 MCP endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                - type: array
      responses:
        "200":
          description: JSON-RPC response
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: Use Authorization: Bearer $PLATPHORM_API_KEY.
    PlatPhormHeader:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY.
