openapi: 3.1.0
info:
  title: Emoji Score API
  version: "17.0"
  description: Deterministic emoji scoring, sentiment scoring, symbolic-expression scoring, Unicode-style proposal scoring, proposal export, model-degraded scaffolding, and MCP tooling for emoji.platphormnews.com.
servers:
  - url: https://emoji.platphormnews.com
security: []
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: Use PLATPHORM_API_KEY for protected actions.
    PlatPhormHeader:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Use PLATPHORM_API_KEY for protected actions.
  schemas:
    RestOk:
      type: object
      properties:
        ok: { type: boolean, const: true }
        data: { type: object }
    RestError:
      type: object
      properties:
        ok: { type: boolean, const: false }
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
            details: { type: object }
paths:
  /api/health:
    get:
      summary: Public health summary.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/health:
    get:
      summary: Standard health summary.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/emojis:
    get:
      summary: List Unicode emoji.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/emojis/search:
    get:
      summary: Search Unicode emoji.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/emojis/categories:
    get:
      summary: List emoji categories.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/emojis/{codepoint}:
    get:
      summary: Get one emoji by code point.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/score:
    post:
      summary: Score an existing emoji or proposal payload.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sentiment/score:
    post:
      summary: Score sentiment and symbolic meaning.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/combinations/score:
    post:
      summary: Score emoji combinations and phrase+emoji expressions.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/proposals/score:
    post:
      summary: Score a Unicode-style proposal.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/proposals:
    get:
      summary: List ephemeral public-safe proposal results in this runtime.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/proposals:
    post:
      summary: Protected server persistence hook; degraded without database.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/proposals/{id}/export:
    post:
      summary: Export proposal markdown when result is available.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/proposals/{id}/download:
    get:
      summary: Download proposal markdown when result is available.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/model/proposal-draft:
    post:
      summary: Protected model-ready proposal writing adapter.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/model/improve-proposal:
    post:
      summary: Protected model-ready improvement adapter.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/model/explain-sentiment:
    post:
      summary: Protected model-ready sentiment explanation adapter.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/model/image-prompt:
    post:
      summary: Protected model-ready image prompt adapter.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/model/accessibility-review:
    post:
      summary: Protected model-ready accessibility review adapter.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/timeline:
    get:
      summary: Unicode emoji timeline.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/unicode/snapshot:
    get:
      summary: Unicode data snapshot metadata.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/unicode/refresh:
    post:
      summary: Protected refresh hook.
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/docs:
    get:
      summary: Machine-readable API docs.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /openapi.yaml:
    get:
      summary: OpenAPI 3.1 specification.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/mcp:
    get:
      summary: MCP metadata and usage.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/mcp:
    post:
      summary: MCP JSON-RPC 2.0 endpoint.
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "401":
          description: Auth required for protected actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
