openapi: 3.1.0
info:
  title: PH3AR API
  version: 1.0.0
  description: Entertainment discovery and trusted PlatPhormNews RSS aggregation.
servers:
  - url: https://ph3ar.com
paths:
  /api/docs:
    get:
      operationId: getApiDocs
      summary: Get public API documentation metadata
      responses:
        '200':
          description: Documentation links and supported public routes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /api/health:
    get:
      operationId: getHealth
      summary: Get public-safe service and compliance health
      responses:
        '200':
          description: Health envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /api/v1/health:
    get:
      operationId: getV1Health
      summary: Get versioned public-safe health
      responses:
        '200':
          description: Health envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /api/feeds:
    get:
      operationId: getNetworkFeeds
      summary: Get trusted PlatPhormNews RSS and Atom aggregation results
      responses:
        '200':
          description: Aggregation envelope with honest per-source outcomes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
  /api/mcp:
    get:
      operationId: getMcpMetadata
      summary: Get public PH3AR MCP metadata and usage
      responses:
        '200':
          description: MCP transport, capability, and method metadata
    post:
      operationId: callMcp
      summary: Call the read-only PH3AR MCP JSON-RPC 2.0 endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/JsonRpcRequest'
                - type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC 2.0 result or error response
        '400':
          description: Malformed JSON or invalid JSON-RPC request
  /api/getMediaDetails:
    post:
      operationId: getMediaDetails
      summary: Look up a movie or television title through OMDB
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string, maxLength: 200 }
      responses:
        '200': { description: OMDB-compatible result }
        '503': { description: OMDB is not configured }
  /api/getMediaDetailsBatch:
    post:
      operationId: getMediaDetailsBatch
      summary: Look up at most 50 movie or television titles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [titles]
              properties:
                titles:
                  type: array
                  maxItems: 50
                  items: { type: string, maxLength: 200 }
      responses:
        '200': { description: Bounded batch result }
  /api/getRecommendation:
    post:
      operationId: getRecommendation
      summary: Generate movie or television recommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [searched]
                  properties:
                    searched: { type: string, maxLength: 500 }
                - type: object
                  required: [lucky]
                  properties:
                    lucky: { const: true }
      responses:
        '200': { description: Recommendation result }
        '429': { description: Rate limit exceeded }
        '503': { description: OpenAI is not configured }
  /api/jobs/generate:
    post:
      operationId: generateJobDraft
      summary: Generate a real job draft without claiming publication
      security:
        - bearerAuth: []
        - platformApiKey: []
      responses:
        '200':
          description: Generated draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          description: Missing or invalid PLATPHORM_API_KEY
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Authentication or OpenAI is not configured
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
    platformApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: The shared PLATPHORM_API_KEY for protected PlatPhorm actions.
  schemas:
    SuccessEnvelope:
      type: object
      required: [ok, data]
      properties:
        ok: { const: true }
        data: { type: object, additionalProperties: true }
    ErrorEnvelope:
      type: object
      required: [ok, error]
      properties:
        ok: { const: false }
        error:
          type: object
          required: [code, message, details]
          properties:
            code: { type: string }
            message: { type: string }
            details: { type: object, additionalProperties: true }
    JsonRpcRequest:
      type: object
      required: [jsonrpc, method]
      properties:
        jsonrpc: { const: '2.0' }
        id:
          oneOf:
            - { type: string }
            - { type: number }
            - { type: 'null' }
        method: { type: string }
        params: {}