{"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-phase1","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":"Integration","description":"Atlas, events, webhooks, provider, and platform integration status."},{"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/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/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/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":{"post":{"tags":["Fingerprint"],"summary":"Submit redacted fingerprint summary with explicit consent","description":"Future protected persistence endpoint. Public Phase 1 accepts only explicit consent and stores redacted summaries when backend storage is configured; otherwise it returns an honest degraded 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/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/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/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/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."}}}}},"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"}}},"FingerprintComponent":{"type":"object","properties":{"type":{"type":"string","enum":["canvas","webgl","audio","fonts","screen","navigator","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":["protected persistence","fingerprint list/detail access","Atlas correlation","webhook operations","events stream access","report generation","cron refresh","admin mutation"]},"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"],"x-platphorm-protected-capabilities":["server fingerprint persistence","server fingerprint list and detail access","Atlas correlation","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."}