openapi: "3.1.0"
info:
  title: "Universal Sign Language Dictionary API"
  version: "1.0.0-phase1"
  description: "Public-safe API for canonical universal symbols, signage categories, learning, quiz, statistics, standards references, emoji integration, discovery, and MCP introspection."
servers:
  - 
    url: "https://usl.platphormnews.com"
  - 
    url: "https://universal-sign-language.platphormnews.com"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Future protected backend actions accept PLATPHORM_API_KEY through X-PlatPhorm-API-Key or Authorization: Bearer. Public-safe Phase 1 reads do not require a key."
paths:
  /api/health:
    get:
      summary: "Public health summary"
      description: "Public health summary. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/health:
    get:
      summary: "Public health summary with API envelope"
      description: "Public health summary with API envelope. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/docs:
    get:
      summary: "Public API documentation"
      description: "Public API documentation. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /openapi.yaml:
    get:
      summary: "OpenAPI YAML"
      description: "OpenAPI YAML. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /openapi.json:
    get:
      summary: "OpenAPI JSON"
      description: "OpenAPI JSON. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/symbols:
    get:
      summary: "List canonical symbols"
      description: "List canonical symbols. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/symbols/{slug}:
    get:
      summary: "Get one canonical symbol"
      description: "Get one canonical symbol. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/categories:
    get:
      summary: "List canonical categories"
      description: "List canonical categories. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/categories/{slug}:
    get:
      summary: "Get one canonical category"
      description: "Get one canonical category. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/search:
    get:
      summary: "Search canonical symbols"
      description: "Search canonical symbols. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/quiz:
    get:
      summary: "Quiz capability and local-progress policy"
      description: "Quiz capability and local-progress policy. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/quiz/questions:
    get:
      summary: "Generate public-safe quiz questions from canonical symbols"
      description: "Generate public-safe quiz questions from canonical symbols. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/quiz/score:
    post:
      summary: "Score a quiz attempt without server persistence"
      description: "Score a quiz attempt without server persistence. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/statistics:
    get:
      summary: "Canonical data statistics"
      description: "Canonical data statistics. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/standards:
    get:
      summary: "Reference standards"
      description: "Reference standards. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/integrations/emoji:
    get:
      summary: "Emoji-linked symbols"
      description: "Emoji-linked symbols. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/v1/integrations/status:
    get:
      summary: "Cross-site integration status"
      description: "Cross-site integration status. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
  /api/mcp:
    get:
      summary: "MCP metadata and usage"
      description: "MCP metadata and usage. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
    post:
      summary: "MCP JSON-RPC 2.0 endpoint"
      description: "MCP JSON-RPC 2.0 endpoint. Public-safe in Phase 1 unless future protected enforcement is enabled for mutating actions."
      responses:
        200:
          description: "Successful public-safe response"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled"
