openapi: 3.1.0
info:
  title: PlatPhorm Reader API
  description: "Public instant translation magnifier, multilingual reading assistance, accessible reading, embeddable widget, PWA metadata, Reader API, and public-safe AI-readable translation layer for PlatPhormNews. Public-safe by default. Protected actions use PLATPHORM_API_KEY only."
  version: 2.1.0
  contact:
    name: PlatPhormNews
    url: "https://platphormnews.com"
    email: "api@platphormnews.com"
  license:
    name: MIT
  x-reader-counts:
    languages: 39
    translationTargets: 39
    activeTranslationLanguages: 15
    degradedTranslationLanguages: 24
    uiLocales: 36
    vernacularPacks: 8
    integrations: 7
    publicRoutes: 40
    protectedRoutes: 9
servers:
  - 
    url: "https://reader.platphormnews.com"
    description: Production
  - 
    url: "http://localhost:3000"
    description: Local development
security:

tags:
  - 
    name: Translation
  - 
    name: Languages
  - 
    name: Widget
  - 
    name: Analytics
  - 
    name: Platform
  - 
    name: MCP
  - 
    name: Policy
paths:
  "/api/health":
    get:
      summary: Platform health summary
      description: "Public-safe Reader health and dependency status."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/health":
    get:
      summary: Versioned health summary
      description: "Same public-safe health shape as /api/health."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/translate":
    get:
      summary: Translation service info
      description: "Returns language counts, provider/degraded status, and supported target metadata."
      tags:
        - Translation
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      summary: Translate text
      description: "Bounded public translation using local dictionary/special-mode paths. Degraded results are explicitly labeled. No provider-grade translation is claimed unless configured."
      tags:
        - Translation
      operationId: translateText
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/TranslateRequest"
            examples:
              simple:
                value:
                  text: Hello world
                  source: en
                  target: es
              autoDetect:
                value:
                  text: こんにちは
                  source: auto
                  target: en
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/TranslateResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/translations":
    get:
      summary: Translation metadata
      description: Returns public language metadata and limits.
      tags:
        - Translation
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      summary: Batch translate text
      description: "Bounded batch translation for public-safe text. High-volume/private use is protected/scaffolded."
      tags:
        - Translation
      operationId: translateBatch
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/BatchTranslateRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/BatchTranslateResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/detect-language":
    post:
      summary: Detect language
      description: "Detects the likely source language using Reader local script/word-pattern detection."
      tags:
        - Translation
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/DetectLanguageRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/DetectLanguageResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/languages":
    get:
      summary: List languages
      description: Lists canonical Reader language metadata.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/languages/{code}":
    get:
      summary: Get language
      description: Gets canonical Reader language metadata by code.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
      parameters:
        - 
          name: code
          in: path
          required: true
          schema:
            type: string
            enum:
              - platphorm
              - en
              - es
              - fr
              - de
              - pt
              - zh
              - ja
              - ko
              - ar
              - hi
              - ru
              - it
              - nl
              - pl
              - tr
              - vi
              - th
              - id
              - ms
              - he
              - uk
              - sv
              - da
              - fi
              - no
              - cs
              - el
              - ro
              - hu
              - bn
              - ta
              - te
              - mr
              - ur
              - fa
              - sw
              - asl
              - simple
  "/api/v1/ui-locales":
    get:
      summary: List UI locales
      description: Lists UI locales derived from the canonical UI locale registry.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/vernaculars":
    get:
      summary: List vernacular packs
      description: Lists canonical Reader vernacular packs.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/vernaculars/{id}":
    get:
      summary: Get vernacular pack
      description: Gets a canonical Reader vernacular pack by id.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
      parameters:
        - 
          name: id
          in: path
          required: true
          schema:
            type: string
            enum:
              - tech
              - crypto
              - legal
              - medical
              - finance
              - gaming
              - "gen-z"
              - academic
  "/api/v1/audio/pronounce":
    post:
      summary: Pronunciation status
      description: "Returns an honest degraded status because Reader has no server-side pronunciation provider configured."
      tags:
        - Translation
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/PronounceRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/DegradedResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/widget/config-schema":
    get:
      summary: Widget config schema
      description: Returns the public Reader widget configuration schema.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/widget/preview":
    post:
      summary: Widget preview
      description: "Validates and returns public-safe widget preview configuration."
      tags:
        - Widget
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/WidgetPreviewRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/WidgetPreviewResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/widget/script":
    get:
      summary: Widget script info
      description: Returns public Reader widget script metadata.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/share":
    post:
      summary: Share target status
      description: "Handles public PWA share-target metadata without storing private text."
      tags:
        - Widget
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ShareRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ShareResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/files/read":
    post:
      summary: Read file status
      description: "Returns honest local-only/degraded file reader status. Text files are handled client-side first."
      tags:
        - Widget
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/FileReadRequest"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/DegradedResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/analytics":
    get:
      summary: Public analytics summary
      description: "Returns public-safe aggregate/degraded analytics summary. Private events require PLATPHORM_API_KEY."
      tags:
        - Analytics
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      summary: "Record public-safe analytics event"
      description: "Records redacted public-safe aggregate analytics metadata. Private text and raw JA4 digest values are redacted."
      tags:
        - Analytics
      operationId: recordAnalytics
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/AnalyticsEvent"
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AnalyticsRecordResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/integrations/status":
    get:
      summary: Integration status
      description: "Returns public-safe downstream integration status with bounded timeouts."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/v1/network":
    get:
      summary: Reader network view
      description: "Returns Reader-centered public-safe network graph/degraded status."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/docs":
    get:
      summary: OpenAPI JSON
      description: Returns this OpenAPI specification as JSON.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/openapi.json":
    get:
      summary: OpenAPI JSON
      description: Returns this OpenAPI specification as JSON.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/openapi.yaml":
    get:
      summary: OpenAPI YAML
      description: Returns this OpenAPI specification as YAML.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/mcp":
    get:
      summary: MCP metadata
      description: "Returns Reader MCP JSON-RPC metadata and supported methods."
      tags:
        - MCP
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      summary: "MCP JSON-RPC 2.0"
      description: "Accepts JSON-RPC 2.0 object or batch for Reader public-safe tools and protected tools requiring PLATPHORM_API_KEY."
      tags:
        - MCP
      operationId: mcpJsonRpc
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              type: object
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/McpResponse"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/llms.txt":
    get:
      summary: llms.txt
      description: Readable dynamic LLM summary.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/llms-full.txt":
    get:
      summary: "llms-full.txt"
      description: Complete dynamic LLM context.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/llms-index.json":
    get:
      summary: "llms-index.json"
      description: "Machine-readable LLM index."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/robots.txt":
    get:
      summary: robots.txt
      description: Robots policy aligned with public/protected boundaries.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/sitemap.xml":
    get:
      summary: sitemap.xml
      description: Public route sitemap with implemented routes only.
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/rss.xml":
    get:
      summary: RSS feed
      description: "Public-safe Reader updates feed."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/.well-known/agents.json":
    get:
      summary: Agent manifest
      description: "Public-safe agent manifest."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/.well-known/agent-policy.json":
    get:
      summary: Agent policy
      description: "Public-safe agent policy."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/.well-known/ai-policy.json":
    get:
      summary: AI policy
      description: "Public-safe AI use policy."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/.well-known/trust.json":
    get:
      summary: Trust policy
      description: "Public-safe Reader trust policy."
      tags:
        - Platform
      responses:
        200:
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        400:
          description: Invalid request
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        401:
          description: Authentication required for protected action
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        429:
          description: Rate limited
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: "X-PlatPhorm-API-Key"
      description: "Protected Reader actions also accept Authorization: Bearer $PLATPHORM_API_KEY."
    PlatPhormBearer:
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
  schemas:
    TranslateRequest:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 5000
        source:
          type: string
          default: auto
        target:
          type: string
          enum:
            - platphorm
            - en
            - es
            - fr
            - de
            - pt
            - zh
            - ja
            - ko
            - ar
            - hi
            - ru
            - it
            - nl
            - pl
            - tr
            - vi
            - th
            - id
            - ms
            - he
            - uk
            - sv
            - da
            - fi
            - no
            - cs
            - el
            - ro
            - hu
            - bn
            - ta
            - te
            - mr
            - ur
            - fa
            - sw
            - asl
            - simple
          default: es
        vernacular:
          type:
            - string
            - null
          enum:
            - tech
            - crypto
            - legal
            - medical
            - finance
            - gaming
            - "gen-z"
            - academic
            - null
        enrich:
          type: boolean
          default: false
        ascii:
          type: boolean
          default: false
        insights:
          type: boolean
          default: false
      required:
        - text
        - target
    TranslateResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: object
        originalText:
          type: string
        translatedText:
          type: string
        sourceLanguage:
          type: string
        targetLanguage:
          type: string
        confidence:
          type: number
        translationMode:
          type: string
        status:
          type: string
          enum:
            - ok
            - degraded
    BatchTranslateRequest:
      type: object
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 25
          items:
            "$ref": "#/components/schemas/TranslateRequest"
        options:
          type: object
      required:
        - items
    BatchTranslateResponse:
      type: object
    DetectLanguageRequest:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 5000
      required:
        - text
    DetectLanguageResponse:
      type: object
    PronounceRequest:
      type: object
      properties:
        text:
          type: string
        language:
          type: string
      required:
        - text
        - language
    WidgetPreviewRequest:
      type: object
      additionalProperties: false
      properties:
        targetLanguage:
          type: string
          enum:
            - platphorm
            - en
            - es
            - fr
            - de
            - pt
            - zh
            - ja
            - ko
            - ar
            - hi
            - ru
            - it
            - nl
            - pl
            - tr
            - vi
            - th
            - id
            - ms
            - he
            - uk
            - sv
            - da
            - fi
            - no
            - cs
            - el
            - ro
            - hu
            - bn
            - ta
            - te
            - mr
            - ur
            - fa
            - sw
            - asl
            - simple
          default: es
        theme:
          type: string
          enum:
            - auto
            - light
            - dark
            - glass
          default: auto
        position:
          type: string
          enum:
            - "bottom-right"
            - "bottom-left"
            - "top-right"
            - "top-left"
            - inline
          default: "bottom-right"
        size:
          type: integer
          minimum: 120
          maximum: 360
          default: 200
        showButton:
          type: boolean
          default: true
        autoActivate:
          type: boolean
          default: false
        enableDictionary:
          type: boolean
          default: true
        enableAsciiArt:
          type: boolean
          default: false
        primaryColor:
          type: string
          pattern: "^#[0-9a-fA-F]{6}$"
          default: "#3b82f6"
        borderRadius:
          type: integer
          minimum: 0
          maximum: 32
          default: 12
      required:
        - targetLanguage
    WidgetPreviewResponse:
      type: object
    ShareRequest:
      type: object
    ShareResponse:
      type: object
    FileReadRequest:
      type: object
    AnalyticsEvent:
      type: object
    AnalyticsRecordResponse:
      type: object
    DegradedResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: object
    McpResponse:
      type: object
    Error:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: object
x-reader-public-routes:
  - /
  - /reader
  - /widget
  - /docs
  - /faq
  - /privacy
  - /terms
  - /open
  - /share
  - /api/docs
  - /openapi.yaml
  - /openapi.json
  - /llms.txt
  - "/llms-full.txt"
  - "/llms-index.json"
  - /robots.txt
  - /sitemap.xml
  - "/sitemap-main.xml"
  - "/sitemap-index.xml"
  - /rss.xml
  - /feed.xml
  - /manifest.webmanifest
  - /api/health
  - /api/v1/health
  - /api/v1/translate
  - /api/v1/languages
  - "/api/v1/ui-locales"
  - /api/v1/vernaculars
  - /api/v1/integrations/status
  - /api/v1/analytics
  - /api/v1/network
  - /api/mcp
  - "/.well-known/mcp.json"
  - "/.well-known/agents.json"
  - "/.well-known/agent-policy.json"
  - "/.well-known/ai-policy.json"
  - "/.well-known/trust.json"
  - "/.well-known/security.txt"
  - "/.well-known/ai-plugin.json"
  - "/.well-known/platphorm.json"