openapi: 3.1.0
info:
  title: "ECHO Content Analytics and Attribution API"
  version: 0.2.0
  description: "Public-safe Echo APIs for content fingerprints, platform registry, degraded monitor jobs, attribution findings, methodology, discovery, and MCP. Protected write/export/provider actions require PLATPHORM_API_KEY."
  contact:
    name: PlatPhormNews
    url: https://platphormnews.com
servers:
  - url: https://echo.platphormnews.com
    description: Production
security:
[]
paths:
  /api/health:
    get:
      summary: "Public health summary"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/health:
    get:
      summary: "Versioned public health summary"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/dashboard:
    get:
      summary: "Public Echo dashboard data"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/content:
    get:
      summary: "List public-safe content items"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
    post:
      summary: "Create an ephemeral public-safe content fingerprint preview"
      security:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentSubmission"
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/BadRequest"
  /api/v1/content/{id}:
    get:
      summary: "Get a public-safe content item"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/platforms:
    get:
      summary: "List Echo platform registry"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/platforms/{slug}:
    get:
      summary: "Get one platform record"
      security:
[]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/jobs:
    get:
      summary: "List monitor jobs"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
    post:
      summary: "Create a degraded public-safe monitor job record"
      security:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MonitorJobSubmission"
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/BadRequest"
  /api/v1/jobs/{id}:
    get:
      summary: "Get one monitor job"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/jobs/{id}/run:
    post:
      summary: "Run a public-safe degraded monitor job without fabricating external findings"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/jobs/{id}/runs:
    get:
      summary: "List monitor job runs"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/findings:
    get:
      summary: "List public-safe findings"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/findings/{id}:
    get:
      summary: "Get one public-safe finding"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/evidence/{id}:
    get:
      summary: "Get a redacted public-safe evidence summary"
      security:
[]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
        404:
          $ref: "#/components/responses/NotFound"
  /api/v1/recovery/cases:
    get:
      summary: "List recovery cases"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/reports:
    get:
      summary: "List public-safe reports"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/integrations/status:
    get:
      summary: "List integration status cards"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/methodology:
    get:
      summary: "Get Echo methodology"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/platform-matrix:
    get:
      summary: "Get platform matrix"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/public-stats:
    get:
      summary: "Get public stats"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/mcp:
    get:
      summary: "Get MCP metadata and usage"
      security:
[]
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
    post:
      summary: "Execute MCP JSON-RPC 2.0 request or batch"
      security:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/JsonRpcRequest"
                - type: array
                  items:
                    $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        200:
          description: "Standard Echo response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                  error:
                    $ref: "#/components/schemas/Error"
  /api/v1/recovery/cases/{id}/outreach:
    post:
      summary: "Protected outreach draft/send workflow"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
  /api/v1/reports/export:
    post:
      summary: "Protected report export"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
  /api/v1/providers/sync:
    post:
      summary: "Protected provider sync"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
  /api/v1/admin/platforms/import:
    post:
      summary: "Protected platform registry import"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
  /api/v1/admin/recalculate:
    post:
      summary: "Protected recalculation"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
  /api/v1/admin/backfill:
    post:
      summary: "Protected backfill"
      security:
        - platphormApiKey:
[]
        - platphormHeaderKey:
[]
      responses:
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
        503:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorEnvelope"
components:
  securitySchemes:
    platphormApiKey:
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
      description: "Use Authorization: Bearer $PLATPHORM_API_KEY for protected Echo actions."
    platphormHeaderKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: "Use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY for protected Echo actions."
  schemas:
    ApiErrorEnvelope:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          $ref: "#/components/schemas/Error"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
    ContentSubmission:
      type: object
      required:
        - canonicalUrl
      properties:
        canonicalUrl:
          type: string
          format: uri
        title:
          type: string
        contentType:
          type: string
        owner:
          type: string
        author:
          type: string
        publishDate:
          type: string
          format: date
        licensePolicy:
          type: string
        attributionRequirement:
          type: string
        canonicalExcerpt:
          type: string
          maxLength: 1000
        publicSafe:
          type: boolean
    MonitorJobSubmission:
      type: object
      required:
        - contentItemId
      properties:
        contentItemId:
          type: string
        jobType:
          type: string
        platforms:
          type: array
          items:
            type: string
        searchStrategy:
          type: string
        schedule:
          type: string
        publicSafe:
          type: boolean
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          const: 2.0
        method:
          type: string
        params:
          type: object
        id:
          oneOf:
            - type: string
            - type: number
            - type: null
  responses:
    BadRequest:
      description: "Protected action requires PLATPHORM_API_KEY"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorEnvelope"
    NotFound:
      description: "Protected action requires PLATPHORM_API_KEY"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorEnvelope"
