openapi: 3.1.0
info:
  title: "PlatPhorm Fingerprint API"
  summary: "Privacy-first browser fingerprint education and public-safe local analysis tooling."
  description: "PlatPhorm Fingerprint exposes deterministic, consent-based browser fingerprint analysis. Public endpoints are educational and privacy-safe. Protected persistence, events, webhooks, Atlas correlation, reports, and administrative actions are scaffolded around PLATPHORM_API_KEY for future enforcement."
  version: 1.0.0-phase3
  contact:
    name: "PlatPhorm News"
    url: https://platphormnews.com
servers:
  -
    url: https://fingerprint.platphormnews.com
    description: "Canonical production service"
tags:
  -
    name: Health
    description: "Public service health and route compliance metadata."
  -
    name: "Local Analysis"
    description: "Public-safe deterministic analysis of user-submitted local summaries."
  -
    name: Fingerprint
    description: "Explicit consent-based redacted persistence and future protected reads."
  -
    name: Stats
    description: "Public-safe aggregate statistics."
  -
    name: Components
    description: "Component catalog, normalization, and deterministic hashing."
  -
    name: Compare
    description: "Exact and fuzzy fingerprint comparison."
  -
    name: JA4
    description: "JA4 digest redaction and JA4M research metadata."
  -
    name: Integration
    description: "Atlas, Monitor, Trace, BrowserOps, Sandbox, Evals, MCP, API, CLI, events, webhooks, provider, and platform integration status."
  -
    name: Policy
    description: "Agent, AI, robots, trust, auth, and public/protected boundary policy."
  -
    name: Discovery
    description: "OpenAPI, LLM, RSS, sitemap, trust, and MCP discovery surfaces."
  -
    name: MCP
    description: "JSON-RPC 2.0 MCP endpoint with public read-only introspection."
security:
[]
paths:
  /api/health:
    get:
      tags:
        - Health
      summary: "Health check"
      description: "Returns public-safe health, privacy, route, auth, and trace metadata."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/health:
    get:
      tags:
        - Health
      summary: "Versioned health check"
      description: "Versioned health endpoint with the same public-safe shape."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analyze/local:
    post:
      tags:
        - "Local Analysis"
      summary: "Analyze local fingerprint"
      description: "Deterministically analyzes a locally collected fingerprint summary. No persistence."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analyze/components:
    post:
      tags:
        - "Local Analysis"
      summary: "Analyze components"
      description: "Returns redacted component explanations and deterministic entropy labels."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/headless:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect headless indicators"
      description: "Analyzes supplied local summary for headless/browser automation indicators."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/automation:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect automation indicators"
      description: "Analyzes supplied local summary for deterministic automation and bot likelihood signals."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/lies:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect lies/tampering"
      description: "Analyzes supplied local summary for deterministic browser API tampering indicators."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/privacy-resistance:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect privacy resistance"
      description: "Analyzes supplied local summary for Brave-like, Firefox RFP-like, Tor-like, reduced entropy, or extension-style resistance hints."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/trust:
    post:
      tags:
        - "Local Analysis"
      summary: "Summarize trust signals"
      description: "Returns a public-safe client trust signal summary. This is not a definitive identity decision."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/ja4m:
    post:
      tags:
        - "Local Analysis"
      summary: "Analyze JA4M metadata"
      description: "Returns JA4M research metadata for MCP and automation client signatures where available."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analysis/{id}:
    get:
      tags:
        - "Local Analysis"
      summary: "Saved analysis lookup status"
      description: "Returns protected/degraded saved-analysis status; raw saved details are not public."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analyze/bot:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect bot indicators"
      description: "Analyzes supplied local summary for bot user-agent indicators."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analyze/lies:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect lies/tampering"
      description: "Analyzes supplied local summary for deterministic browser API tampering indicators."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/analyze/resistance:
    post:
      tags:
        - "Local Analysis"
      summary: "Detect resistance mode"
      description: "Analyzes supplied local summary for possible privacy-resistance mode indicators."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/components:
    get:
      tags:
        - Components
      summary: "Component catalog"
      description: "Returns the public-safe fingerprint component catalog."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/components/{type}:
    get:
      tags:
        - Components
      summary: "Component detail"
      description: "Returns a public-safe component definition by type."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/components/hash:
    post:
      tags:
        - Components
      summary: "Hash a component"
      description: "Canonicalizes and hashes a caller-provided component payload without returning raw values."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/components/normalize:
    post:
      tags:
        - Components
      summary: "Normalize a component"
      description: "Returns deterministic normalized component data with volatile fields removed."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/compare:
    post:
      tags:
        - "Local Analysis"
      summary: "Compare two local fingerprint summaries"
      description: "Compares two caller-provided local snapshots. No server lookup or persistence is performed."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompareRequest"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompareResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/compare/components:
    post:
      tags:
        - Components
      summary: "Compare components"
      description: "Compares caller-provided components or fingerprints with weighted fuzzy scoring."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/compare/{id}:
    get:
      tags:
        - Compare
      summary: "Saved comparison lookup status"
      description: "Returns protected/degraded saved-comparison status; raw saved comparisons are not public."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/export:
    post:
      tags:
        - "Local Analysis"
      summary: "Export a redacted local analysis report"
      description: "Builds an explicit user-requested, redacted JSON report from caller-provided local data."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintInput"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/fingerprint/local-report:
    post:
      tags:
        - Components
      summary: "Create local redacted report"
      description: "Builds a redacted local report from caller-provided fingerprint data."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/fingerprint/export:
    post:
      tags:
        - Components
      summary: "Export fingerprint report"
      description: "Alias for redacted local report generation. Protected report exports require PLATPHORM_API_KEY when durable backends are configured."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/fingerprint:
    post:
      tags:
        - Fingerprint
      summary: "Submit redacted fingerprint summary with explicit consent"
      description: "Protected persistence endpoint. Public local analysis does not store server records. Durable redacted submission requires PLATPHORM_API_KEY plus explicit consent; otherwise it returns an honest local-only state."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FingerprintSubmission"
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FingerprintSubmitResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
    get:
      get:
        tags:
          - Fingerprint
        summary: "List redacted fingerprint records"
        description: "Returns public-safe metadata without PLATPHORM_API_KEY. Protected list access is scaffolded for future enforcement and must never expose raw component data publicly."
        security:
[]
        responses:
          200:
            description: "Request completed"
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ApiEnvelope"
          400:
            description: "Invalid request"
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/ApiEnvelope"
          401:
            description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
          500:
            description: "Unexpected server error with public-safe error body."
  /api/v1/fingerprint/{id}:
    get:
      tags:
        - Fingerprint
      summary: "Get redacted fingerprint record"
      description: "Returns public-safe protected-route metadata without PLATPHORM_API_KEY. Future protected access may return redacted server summaries only."
      parameters:
        -
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FingerprintDetailResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/overview:
    get:
      tags:
        - Stats
      summary: "Aggregate stats overview"
      description: "Returns non-identifying aggregate statistics or degraded storage status."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/components:
    get:
      tags:
        - Stats
      summary: "Aggregate component stats"
      description: "Returns public-safe aggregate component stats or degraded labels."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/browsers:
    get:
      tags:
        - Stats
      summary: "Aggregate browser stats"
      description: "Returns public-safe aggregate browser stats or degraded labels."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/devices:
    get:
      tags:
        - Stats
      summary: "Aggregate device stats"
      description: "Returns public-safe aggregate device stats or degraded labels."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/headless:
    get:
      tags:
        - Stats
      summary: "Aggregate headless stats"
      description: "Returns public-safe aggregate headless stats or degraded labels."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/stats/privacy:
    get:
      tags:
        - Stats
      summary: "Aggregate privacy stats"
      description: "Returns public-safe aggregate privacy-resistance stats or degraded labels."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/ja4/digest:
    post:
      tags:
        - Components
      summary: "Hash JA4 digest metadata"
      description: "Accepts caller-provided JA4 digest metadata and returns hash-only public-safe output unless protected persistence is authorized."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/ja4/summary:
    get:
      tags:
        - JA4
      summary: "JA4 and JA4M summary"
      description: "Returns public-safe JA4 redaction and JA4M research policy."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/ja4/correlate:
    post:
      tags:
        - Integration
      summary: "JA4 correlation"
      description: "Protected/degraded JA4 digest correlation. No fake correlation output is returned."
      security:
        -
          PlatformApiKey:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/ja4/correlations:
    get:
      tags:
        - JA4
      summary: "JA4 correlations"
      description: "Returns protected/degraded JA4 correlation state without raw digest exposure."
      security:
[]
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations:
    get:
      tags:
        - Integration
      summary: "Integration status"
      description: "Returns all public-safe integration states."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/provider/status:
    get:
      tags:
        - Integration
      summary: "Model provider status"
      description: "Returns server-only backend model scaffolding status and deterministic fallback state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/status:
    get:
      tags:
        - Integration
      summary: "Integration status"
      description: "Returns public-safe Atlas, Monitor, Trace, ThreatRelay, Docs, Sheets, Decks, Evals, BrowserOps, and Webhooks status."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/atlas:
    get:
      tags:
        - Integration
      summary: "Atlas correlation status"
      description: "Returns honest degraded/public-safe Atlas status unless protected correlation is configured."
      security:
[]
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/monitor:
    get:
      tags:
        - Integration
      summary: "Monitor integration status"
      description: "Returns Monitor integration status or degraded state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/trace:
    get:
      tags:
        - Integration
      summary: "Trace integration status"
      description: "Returns Trace header and correlation status or degraded state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/browserops:
    get:
      tags:
        - Integration
      summary: "BrowserOps integration status"
      description: "Returns BrowserOps integration status or degraded state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/sandbox:
    get:
      tags:
        - Integration
      summary: "Sandbox integration status"
      description: "Returns Sandbox integration status or degraded state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/evals:
    get:
      tags:
        - Integration
      summary: "Evals integration status"
      description: "Returns Evals integration status or degraded state."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/mcp:
    get:
      tags:
        - Integration
      summary: "MCP integration status"
      description: "Returns MCP integration status."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/api:
    get:
      tags:
        - Integration
      summary: "API Hub integration status"
      description: "Returns API catalog integration status."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/integrations/cli:
    get:
      tags:
        - Integration
      summary: "CLI integration status"
      description: "Returns platphormctl integration status and examples."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/events:
    get:
      tags:
        - Integration
      summary: "Events stream status"
      description: "Returns public-safe degraded metadata; protected event stream access is future PLATPHORM_API_KEY work."
      security:
[]
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/events:
    get:
      tags:
        - Integration
      summary: "Versioned events stream status"
      description: "Returns public-safe degraded metadata; protected event stream access is future PLATPHORM_API_KEY work."
      security:
[]
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/webhooks:
    post:
      tags:
        - Integration
      summary: "Webhook operation"
      description: "Future protected webhook endpoint. Public Phase 1 returns AUTH_REQUIRED/degraded metadata unless PLATPHORM_API_KEY enforcement/configuration is available."
      security:
        -
          PlatformApiKey:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntegrationStatusResponse"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/webhooks/status:
    get:
      tags:
        - Integration
      summary: "Webhook status"
      description: "Returns webhook signature and protected delivery status."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/webhooks/test:
    post:
      tags:
        - Integration
      summary: "Webhook test"
      description: "Protected/degraded webhook test endpoint. No fake delivery success is returned."
      security:
        -
          PlatformApiKey:
[]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/agent-policy:
    get:
      tags:
        - Policy
      summary: "Agent policy"
      description: "Returns public agent policy and protected action boundaries."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/agent-policy/platforms:
    get:
      tags:
        - Policy
      summary: "Agent platforms"
      description: "Returns agent platform categories without invented crawler strings."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/agent-policy/platforms/{id}:
    get:
      tags:
        - Policy
      summary: "Agent platform detail"
      description: "Returns a specific platform category policy."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/agent-policy/robots:
    get:
      tags:
        - Policy
      summary: "Robots policy"
      description: "Returns generated robots policy summary."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/v1/agent-policy/summary:
    get:
      tags:
        - Policy
      summary: "Agent policy summary"
      description: "Returns agent policy summary."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /api/mcp:
    get:
      tags:
        - MCP
      summary: "MCP metadata"
      description: "Returns public read-only MCP metadata and JSON-RPC usage."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
    post:
      tags:
        - MCP
      summary: "MCP JSON-RPC endpoint"
      description: "Accepts JSON-RPC 2.0 object or batch for public read-only introspection and bounded local-analysis tools."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        200:
          description: "JSON-RPC 2.0 response or batch response"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/docs:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON"
      description: "Returns this OpenAPI document as JSON."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /openapi.json:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON"
      description: "Returns this OpenAPI document as JSON."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /openapi.yaml:
    get:
      tags:
        - Discovery
      summary: "OpenAPI YAML"
      description: "Returns this OpenAPI document as YAML."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /llms.txt:
    get:
      tags:
        - Discovery
      summary: "LLMs text"
      description: "Readable AI-oriented service summary."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /llms-full.txt:
    get:
      tags:
        - Discovery
      summary: "LLMs full text"
      description: "Detailed AI-oriented service summary."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /llms-index.json:
    get:
      tags:
        - Discovery
      summary: "LLMs index"
      description: "Structured AI-oriented service summary."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /rss.xml:
    get:
      tags:
        - Discovery
      summary: "RSS feed"
      description: "Public-safe education/changelog RSS feed."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /feed.xml:
    get:
      tags:
        - Discovery
      summary: "Atom feed"
      description: "Public-safe education/changelog Atom feed."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /sitemap.xml:
    get:
      tags:
        - Discovery
      summary: Sitemap
      description: "Public URL sitemap with no protected mutation routes."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /sitemap-main.xml:
    get:
      tags:
        - Discovery
      summary: "Main sitemap"
      description: "Public URL sitemap with discovery surfaces."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /sitemap-index.xml:
    get:
      tags:
        - Discovery
      summary: "Sitemap index"
      description: "Sitemap index."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /robots.txt:
    get:
      tags:
        - Discovery
      summary: "Robots policy"
      description: "Crawler policy generated from the public agent policy."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/mcp.json:
    get:
      tags:
        - Discovery
      summary: "MCP manifest"
      description: "Public read-only MCP manifest."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/agents.json:
    get:
      tags:
        - Discovery
      summary: "Agents manifest"
      description: "Public agent manifest."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/agent-policy.json:
    get:
      tags:
        - Discovery
      summary: "Agent policy"
      description: "Public agent policy manifest."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/ai-policy.json:
    get:
      tags:
        - Discovery
      summary: "AI policy"
      description: "Public AI client policy manifest."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/security.txt:
    get:
      tags:
        - Discovery
      summary: "Security contact"
      description: "Security contact text file."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
  /.well-known/trust.json:
    get:
      tags:
        - Discovery
      summary: "Trust policy"
      description: "Public trust and redaction policy."
      responses:
        200:
          description: "Request completed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiEnvelope"
        401:
          description: "Future protected action requires PLATPHORM_API_KEY when enforcement is enabled."
        500:
          description: "Unexpected server error with public-safe error body."
components:
  securitySchemes:
    PlatformApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: "Future protected-action key. Requests may also use Authorization: Bearer $PLATPHORM_API_KEY. Public-safe Phase 1 endpoints do not require this key by default."
  schemas:
    ApiEnvelope:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
        data:
          type: object
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
        traceId:
          type: string
    FingerprintInput:
      type: object
      description: "Caller-provided local fingerprint summary. Raw high-entropy details should be redacted client-side before protected persistence."
      properties:
        visitorHash:
          type: string
        fuzzyHash:
          type: string
        confidenceScore:
          type: number
        components:
          type: array
          items:
            $ref: "#/components/schemas/FingerprintComponent"
        isHeadless:
          type: boolean
        isBot:
          type: boolean
        hasLies:
          type: boolean
        resistanceMode:
          type: string
    AlgorithmVersions:
      type: object
      properties:
        algorithmVersion:
          type: string
          example: fingerprint-analysis-v3.0.0
        componentSchemaVersion:
          type: string
          example: fingerprint-components-v3.0.0
        hashVersion:
          type: string
          example: sha256-stable-json-v3.0.0
        fuzzyHashVersion:
          type: string
          example: weighted-component-vector-v3.0.0
        detectionVersion:
          type: string
          example: deterministic-signal-rules-v3.0.0
    FingerprintComponent:
      type: object
      properties:
        type:
          type: string
          enum:
            - canvas
            - webgl
            - audio
            - fonts
            - screen
            - navigator
            - css
            - media
            - permissions
            - storage
            - timezone
            - domrect
            - ja4h
            - connection
        hash:
          type: string
        confidence:
          type: number
        data:
          type: object
          description: "Local input only. Public responses return redactedData instead."
    FingerprintSubmission:
      allOf:
        -
          $ref: "#/components/schemas/FingerprintInput"
        -
          type: object
          required:
            - consentedToSubmit
          properties:
            consentedToSubmit:
              type: boolean
              const: true
    AnalysisResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
    CompareRequest:
      type: object
      required:
        - fingerprintA
        - fingerprintB
      properties:
        fingerprintA:
          $ref: "#/components/schemas/FingerprintInput"
        fingerprintB:
          $ref: "#/components/schemas/FingerprintInput"
    CompareResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
    ExportResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
    FingerprintSubmitResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
    FingerprintDetailResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
    IntegrationStatusResponse:
      allOf:
        -
          $ref: "#/components/schemas/ApiEnvelope"
x-platphorm-auth-policy:
  publicSafeDefault: true
  requireApiKey: false
  configured: true
  acceptedHeaders:
    - "Authorization: Bearer $PLATPHORM_API_KEY"
    - "X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"
  futureProtectedActions:
    - "server fingerprint persistence"
    - "fingerprint list/detail access"
    - "Atlas correlation"
    - "webhook operations"
    - "events stream access"
    - "report generation"
    - "cron refresh"
    - "admin mutation"
x-platphorm-algorithm-versions:
  algorithmVersion: fingerprint-analysis-v3.0.0
  componentSchemaVersion: fingerprint-components-v3.0.0
  hashVersion: sha256-stable-json-v3.0.0
  fuzzyHashVersion: weighted-component-vector-v3.0.0
  detectionVersion: deterministic-signal-rules-v3.0.0
x-platphorm-public-capabilities:
  - "local component availability and confidence"
  - "deterministic entropy labels"
  - "headless and browser automation indicators"
  - "bot user-agent indicators"
  - "JavaScript lies and tampering indicators"
  - "privacy-resistance mode hints"
  - "local snapshot comparison"
  - "privacy-safe aggregate stats"
  - "JA4 and JA4M redaction policy inspection"
  - "MCP/API-accessible public-safe fingerprint intelligence"
x-platphorm-protected-capabilities:
  - "server fingerprint persistence"
  - "server fingerprint list and detail access"
  - "raw or reversible identifier access"
  - "internal trust scoring"
  - "JA4 digest correlation"
  - "Atlas correlation"
  - "Trace private correlation"
  - "Monitor signal publishing"
  - "BrowserOps collection triggers"
  - "Sandbox execution triggers"
  - "Evals run triggers"
  - "webhook operations"
  - "event stream access"
  - "report generation"
  - "sync and cron refresh"
  - "administrative route and trusted-domain mutation"
x-platphorm-privacy-boundary: "Local analysis is public-safe. Explicit server submission is consent-based, bounded, and redacted. Raw fingerprint records are not public."
