openapi: 3.1.0
info:
  title: PlatPhorm Notes
  version: 95baf43
  description: Public learning notepad that enriches notes, detects terminology, looks up PlatPhorm Dictionary definitions, and stages human-approved dictionary submissions.
servers:
  - url: https://note.platphormnews.com
    description: Canonical PlatPhorm Notes endpoint
  - url: https://notes.platphormnews.com
    description: Supported legacy alias; requests redirect to the canonical endpoint
components:
  securitySchemes:
    PlatPhormServiceKey:
      type: http
      scheme: bearer
      description: Backend service-to-service calls use PLATPHORM_API_KEY. Visitors do not enter this key.
paths:
  /api/health:
    get:
      summary: Health check
      responses:
        "200":
          description: Health payload
  /api/v1/health:
    get:
      summary: Versioned health check
      responses:
        "200":
          description: Health payload
  /api/docs:
    get:
      summary: API docs metadata
      responses:
        "200":
          description: API docs
  /api/mcp:
    get:
      summary: MCP metadata
      responses:
        "200":
          description: MCP metadata
    post:
      summary: MCP JSON-RPC 2.0 endpoint
      responses:
        "200":
          description: JSON-RPC response
  /api/notes:
    get:
      summary: GET /api/notes
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    post:
      summary: POST /api/notes
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}:
    get:
      summary: GET /api/notes/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    put:
      summary: PUT /api/notes/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    delete:
      summary: DELETE /api/notes/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/restore:
    post:
      summary: POST /api/notes/[id]/restore
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/versions:
    get:
      summary: GET /api/notes/[id]/versions
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/versions/{versionId}/restore:
    post:
      summary: POST /api/notes/[id]/versions/[versionId]/restore
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/terms:
    get:
      summary: GET /api/notes/[id]/terms
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/analyze:
    post:
      summary: POST /api/notes/[id]/analyze
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/publish/docs:
    post:
      summary: POST /api/notes/[id]/publish/docs
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/publish/opendocs:
    post:
      summary: POST /api/notes/[id]/publish/opendocs
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notes/{id}/export/sheets:
    post:
      summary: POST /api/notes/[id]/export/sheets
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notebooks:
    get:
      summary: GET /api/notebooks
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    post:
      summary: POST /api/notebooks
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/notebooks/{id}:
    get:
      summary: GET /api/notebooks/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    put:
      summary: PUT /api/notebooks/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    delete:
      summary: DELETE /api/notebooks/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/tags:
    get:
      summary: GET /api/tags
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    post:
      summary: POST /api/tags
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/tags/{id}:
    get:
      summary: GET /api/tags/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    put:
      summary: PUT /api/tags/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    delete:
      summary: DELETE /api/tags/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/search:
    get:
      summary: GET /api/search
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/search/notes:
    get:
      summary: GET /api/search/notes
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/search/terms:
    get:
      summary: GET /api/search/terms
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/search/submissions:
    get:
      summary: GET /api/search/submissions
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/ai/analyze:
    post:
      summary: POST /api/ai/analyze
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/ai/define:
    post:
      summary: POST /api/ai/define
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/ai/summarize:
    post:
      summary: POST /api/ai/summarize
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/ai/suggest-tags:
    post:
      summary: POST /api/ai/suggest-tags
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/ai/related-notes:
    post:
      summary: POST /api/ai/related-notes
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/dictionary/lookup:
    get:
      summary: GET /api/dictionary/lookup
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/dictionary/batch-lookup:
    post:
      summary: POST /api/dictionary/batch-lookup
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/dictionary/submit:
    post:
      summary: POST /api/dictionary/submit
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/dictionary/trending:
    get:
      summary: GET /api/dictionary/trending
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/dictionary/submissions:
    get:
      summary: GET /api/dictionary/submissions
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/docs/publish:
    post:
      summary: POST /api/integrations/docs/publish
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/docs/clip:
    post:
      summary: POST /api/integrations/docs/clip
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/opendocs/publish:
    post:
      summary: POST /api/integrations/opendocs/publish
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/opencontent/preview:
    post:
      summary: POST /api/integrations/opencontent/preview
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/opencontent/submit:
    post:
      summary: POST /api/integrations/opencontent/submit
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/sheets/export:
    post:
      summary: POST /api/integrations/sheets/export
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/sheets/pull:
    get:
      summary: GET /api/integrations/sheets/pull
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    post:
      summary: POST /api/integrations/sheets/pull
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/sheets/embed:
    get:
      summary: GET /api/integrations/sheets/embed
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/ascii/capabilities:
    get:
      summary: GET /api/integrations/ascii/capabilities
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/ascii/preview:
    post:
      summary: POST /api/integrations/ascii/preview
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/ascii/embed:
    get:
      summary: GET /api/integrations/ascii/embed
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/emoji/preview:
    post:
      summary: POST /api/integrations/emoji/preview
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/emoji/score:
    post:
      summary: POST /api/integrations/emoji/score
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/emoji/embed:
    get:
      summary: GET /api/integrations/emoji/embed
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/phorm/capabilities:
    get:
      summary: GET /api/integrations/phorm/capabilities
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/phorm/embed:
    get:
      summary: GET /api/integrations/phorm/embed
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/phorm/preview:
    post:
      summary: POST /api/integrations/phorm/preview
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/svg/capabilities:
    get:
      summary: GET /api/integrations/svg/capabilities
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/svg/embed:
    get:
      summary: GET /api/integrations/svg/embed
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/svg/preview:
    post:
      summary: POST /api/integrations/svg/preview
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/agentops/handoff:
    post:
      summary: POST /api/integrations/agentops/handoff
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/integrations/status:
    get:
      summary: GET /api/integrations/status
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/mcp/commands:
    get:
      summary: GET /api/mcp/commands
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/resources:
    post:
      summary: POST /api/resources
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/resources/{id}:
    get:
      summary: GET /api/resources/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
    delete:
      summary: DELETE /api/resources/[id]
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/resources/supported-media:
    get:
      summary: GET /api/resources/supported-media
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/workflows:
    get:
      summary: GET /api/workflows
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
  /api/workflows/runs:
    post:
      summary: POST /api/workflows/runs
      responses:
        "200":
          description: PlatPhorm ok/error envelope
        "400":
          description: Invalid request
        "503":
          description: Honest degraded state when backing service is unavailable
