openapi: "3.1.0"
info: 
  title: "Polymaths API"
  description: "Public-safe educational API for polymathy principles, historical polymath profiles, methodology frameworks, resources, quotes, deterministic learning paths, mentor status, and MCP discovery."
  version: "1.0.0"
  contact: 
    name: "PlatPhormNews"
    url: "https://platphormnews.com"
    email: "hello@platphormnews.com"
  license: 
    name: "MIT and CC BY 4.0"
servers: 
  - 
    url: "https://polymaths.platphormnews.com"
    description: "Production"
security: []
tags: 
  - 
    name: "Health"
  - 
    name: "Content"
  - 
    name: "Learning"
  - 
    name: "Mentor"
  - 
    name: "Discovery"
  - 
    name: "MCP"
paths: 
  "/api/health": 
    get: 
      summary: "Health summary"
      tags: 
        - "Health"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/health": 
    get: 
      summary: "Versioned health summary"
      tags: 
        - "Health"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/polymaths": 
    get: 
      summary: "List 20 canonical polymath profiles"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/polymaths/{slug}": 
    get: 
      summary: "Get a canonical polymath profile by slug"
      tags: 
        - "Content"
      parameters: 
        - 
          name: "slug"
          in: "path"
          required: true
          schema: 
            type: "string"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/principles": 
    get: 
      summary: "List 7 polymathy principles"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/principles/{slug}": 
    get: 
      summary: "Get a principle by slug"
      tags: 
        - "Content"
      parameters: 
        - 
          name: "slug"
          in: "path"
          required: true
          schema: 
            type: "string"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/methodology": 
    get: 
      summary: "List 6 methodology frameworks"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/methodology/{slug}": 
    get: 
      summary: "Get a methodology framework by slug"
      tags: 
        - "Content"
      parameters: 
        - 
          name: "slug"
          in: "path"
          required: true
          schema: 
            type: "string"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/quotes": 
    get: 
      summary: "List 85 canonical quotes"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/resources": 
    get: 
      summary: "List 9 curated resources"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/resources/{slug}": 
    get: 
      summary: "Get a resource by slug"
      tags: 
        - "Content"
      parameters: 
        - 
          name: "slug"
          in: "path"
          required: true
          schema: 
            type: "string"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/timeline": 
    get: 
      summary: "Chronological polymath timeline"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/knowledge-map": 
    get: 
      summary: "Static canonical knowledge map"
      tags: 
        - "Content"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/learning-paths": 
    post: 
      summary: "Generate a deterministic local-only learning path"
      tags: 
        - "Learning"
      description: "Public-safe Phase 1 generator. It does not persist server-side; clients should save non-sensitive drafts in browser storage."
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/learning-paths/{id}": 
    get: 
      summary: "Return local-only storage guidance for a learning path id"
      tags: 
        - "Learning"
      parameters: 
        - 
          name: "id"
          in: "path"
          required: true
          schema: 
            type: "string"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/mentor": 
    post: 
      summary: "Ask the mentor when backend model support is configured"
      tags: 
        - "Mentor"
      description: "Returns an honest degraded response when no server-side model provider is configured."
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/mentor/status": 
    get: 
      summary: "Get backend mentor/model configured or degraded status"
      tags: 
        - "Mentor"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/v1/network": 
    get: 
      summary: "Canonical network discovery from root graph and base sitemap index"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/api/mcp": 
    get: 
      summary: "MCP metadata and usage"
      tags: 
        - "MCP"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
    post: 
      summary: "MCP JSON-RPC 2.0 endpoint"
      tags: 
        - "MCP"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/llms.txt": 
    get: 
      summary: "Readable LLM summary"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/llms-full.txt": 
    get: 
      summary: "Full AI-readable Polymaths context"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/llms-index.json": 
    get: 
      summary: "Structured LLM index"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/rss.xml": 
    get: 
      summary: "RSS feed"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/feed.xml": 
    get: 
      summary: "Atom feed"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/sitemap.xml": 
    get: 
      summary: "Dynamic sitemap"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/sitemap-main.xml": 
    get: 
      summary: "Main public page sitemap"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
  "/.well-known/trust.json": 
    get: 
      summary: "Trust and public/protected boundary policy"
      tags: 
        - "Discovery"
      responses: 
        200: 
          description: "Public-safe response"
          content: 
            "application/json": 
              schema: 
                "$ref": "#/components/schemas/RestEnvelope"
        404: 
          description: "Not found"
        503: 
          description: "Degraded or unavailable"
components: 
  securitySchemes: 
    PlatPhormBearer: 
      type: "http"
      scheme: "bearer"
      description: "Future protected-action auth: Authorization: Bearer $PLATPHORM_API_KEY"
    PlatPhormApiKeyHeader: 
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Future protected-action auth: X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"
  schemas: 
    RestEnvelope: 
      type: "object"
      properties: 
        ok: 
          type: "boolean"
        data: 
{}
        error: 
          type: "object"
          properties: 
            code: 
              type: "string"
            message: 
              type: "string"
            details: 
              type: "object"
        meta: 
          type: "object"
x-polymaths-counts: 
  polymathCount: 20
  principleCount: 7
  methodologyCount: 6
  resourceCount: 9
  quoteCount: 85
  learningPathTemplateCount: 4
  disciplineCount: 52
  eraCount: 5
  knowledgeMapNodeCount: 47
  knowledgeMapEdgeCount: 43
  source: "canonical static content"
  updatedAt: "2026-05-10T00:00:00.000Z"
x-auth-policy: 
  publicSafeDefault: true
  futureProtectedKey: "PLATPHORM_API_KEY"
  enforcementDefault: "PLATPHORM_REQUIRE_API_KEY=false"