openapi: 3.1.0
info:
  title: "JC PenTest Harness API"
  version: "1.1.0"
  description: "Evidence-first, responsible-use API for dry-run planning, protected real-run orchestration, model status, findings, scorecards, reports, MCP, and discovery."
servers:
  - url: https://pentest.platphormnews.com
  - url: https://pentest.platphormnews.com
security:
  - PlatPhormBearer: []
  - PlatPhormApiKey: []
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: Bearer PLATPHORM_API_KEY
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
paths:
  /api/health:
    get:
      summary: "Public health status"
      responses:
        '200':
          description: OK
  /api/coverage:
    get:
      summary: "Public class coverage summary"
      responses:
        '200':
          description: OK
  /api/events:
    get:
      summary: "Public event outbox"
      responses:
        '200':
          description: OK
  /api/findings:
    get:
      summary: "Public finding summaries"
      responses:
        '200':
          description: OK
  /api/stats:
    get:
      summary: "Public dashboard stats"
      responses:
        '200':
          description: OK
  /api/v1/health:
    get:
      summary: "Versioned health status"
      responses:
        '200':
          description: OK
  /api/v1/setup/status:
    get:
      summary: "Setup and integration status"
      responses:
        '200':
          description: OK
  /api/v1/setup/validate:
    post:
      summary: "Validate setup draft and scope"
      responses:
        '200':
          description: OK
  /api/v1/responsible-use:
    get:
      summary: "Responsible-use policy"
      responses:
        '200':
          description: OK
  /api/v1/responsible-use/accept:
    post:
      summary: "Accept responsible-use policy"
      responses:
        '200':
          description: OK
  /api/v1/scopes/validate:
    post:
      summary: "Validate target scope without active calls"
      responses:
        '200':
          description: OK
  /api/v1/runs:
    get:
      summary: "List protected local run records"
      responses:
        '200':
          description: OK
    post:
      summary: "Create run record"
      responses:
        '200':
          description: OK
  /api/v1/runs/dry-run:
    post:
      summary: "Execute public-safe demo dry run or protected custom dry run"
      responses:
        '200':
          description: OK
  /api/v1/runs/real-run:
    post:
      summary: "Request protected real run"
      responses:
        '200':
          description: OK
  /api/v1/models:
    get:
      summary: "Model roster"
      responses:
        '200':
          description: OK
  /api/v1/models/status:
    get:
      summary: "Server-side model and key-source status"
      responses:
        '200':
          description: OK
  /api/v1/integrations/status:
    get:
      summary: "Integration status"
      responses:
        '200':
          description: OK
  /api/v1/integrations/platphorm/registry:
    get:
      summary: "Configured PlatPhorm service registry"
      responses:
        '200':
          description: OK
  /api/v1/integrations/platphorm/discovery:
    get:
      summary: "Live public discovery summary for Sandbox and BrowserOps"
      responses:
        '200':
          description: OK
  /api/v1/integrations/sandbox/preview:
    post:
      summary: "Preview a Sandbox handoff payload without delivery"
      responses:
        '200':
          description: OK
  /api/v1/integrations/browserops/preview:
    post:
      summary: "Preview a BrowserOps handoff payload without delivery"
      responses:
        '200':
          description: OK
  /api/v1/integrations/sandbox/handoff:
    post:
      summary: "Send a protected handoff to PlatPhorm Sandbox"
      responses:
        '200':
          description: OK
  /api/v1/integrations/browserops/handoff:
    post:
      summary: "Send a protected handoff to PlatPhorm BrowserOps"
      responses:
        '200':
          description: OK
  /api/v1/events:
    get:
      summary: "Versioned event outbox"
      responses:
        '200':
          description: OK
  /api/v1/webhooks:
    get:
      summary: "Webhook event catalog"
      responses:
        '200':
          description: OK
  /api/v1/reports:
    get:
      summary: "Public-safe report package index"
      responses:
        '200':
          description: OK
  /api/v1/reports/{runId}:
    get:
      summary: "Public-safe report package by run id"
      responses:
        '200':
          description: OK
  /api/v1/runtime/credentials:
    get:
      summary: "Runtime credential presence without exposing raw values"
      responses:
        '200':
          description: OK
  /api/v1/runtime/credentials/check:
    post:
      summary: "Check runtime credential presence without persistence"
      responses:
        '200':
          description: OK
  /api/v1/sandbox/jobs:
    post:
      summary: "Create sandbox job when configured"
      responses:
        '200':
          description: OK
  /api/mcp:
    get:
      summary: "MCP metadata"
      responses:
        '200':
          description: OK
    post:
      summary: "MCP JSON-RPC 2.0 endpoint"
      responses:
        '200':
          description: OK
