{"openapi":"3.1.0","info":{"title":"PlatPhorm Trace Observatory API","version":"0.13.0","description":"Canonical PlatPhormNews observability API for W3C trace context, trace ingestion, span lifecycle, async jobs, aggregation, public-safe evidence, and MCP Trace Observatory tools. Public reads are open; protected ingestion and mutations require PLATPHORM_API_KEY.","contact":{"name":"Michael Barbine","url":"https://platphormnews.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"x-logo":{"url":"https://trace.platphormnews.com/icon-512.png"}},"servers":[{"url":"https://trace.platphormnews.com/api/v1","description":"Production API"}],"tags":[{"name":"traces","description":"Trace ingestion and retrieval"},{"name":"sessions","description":"Session management and aggregation"},{"name":"spans","description":"Span lifecycle start, heartbeat, completion, failure, and late/orphan handling"},{"name":"async","description":"Async trace and job lifecycle APIs"},{"name":"workflows","description":"Public workflow templates and protected trace-linked execution"},{"name":"aggregation","description":"Public-safe trace aggregation, latency, service, propagation, and correlation summaries"},{"name":"observability","description":"Observed per-system journey context and telemetry coverage"},{"name":"mcp","description":"JSON-RPC MCP Trace Observatory endpoint"},{"name":"analysis","description":"AI-powered trace analysis"},{"name":"export","description":"Trace export and sharing"},{"name":"live","description":"Real-time trace streaming"},{"name":"network","description":"Trusted-domain and route-compliance visibility"},{"name":"health","description":"API health and status"}],"paths":{"/api/health":{"get":{"tags":["health"],"summary":"Read the public Trace health summary","operationId":"getHealth","responses":{"200":{"description":"Public-safe Trace health envelope"}}}},"/api/v1/health":{"get":{"tags":["health"],"summary":"Read the versioned public Trace health summary","operationId":"getVersionedHealth","responses":{"200":{"description":"Versioned public-safe Trace health envelope"}}}},"/traces":{"get":{"tags":["traces"],"summary":"List traces","description":"List public traces whose persisted structure proves a meaningful action. Historical rudimentary records are hidden from public listings and direct public inspection; protected forensic queries require PLATPHORM_API_KEY.","operationId":"listTraces","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque stable cursor from pagination.next_cursor. Takes precedence over page."},{"name":"include_total","in":"query","schema":{"type":"boolean","default":true},"description":"Set false for lower-cost cursor pagination without an exact total."},{"name":"status","in":"query","schema":{"type":"string","enum":["running","completed","error","timeout"]}},{"name":"agent","in":"query","schema":{"type":"string"},"description":"Filter by agent name (partial match)"},{"name":"min_health","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_health","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Filter by source domain"},{"name":"service","in":"query","schema":{"type":"string"},"description":"Filter trace or span service/source metadata"},{"name":"model","in":"query","schema":{"type":"string"},"description":"Filter trace or span model telemetry"},{"name":"fingerprint","in":"query","schema":{"type":"string"},"description":"Filter by public-safe JA4 digest group"},{"name":"tool","in":"query","schema":{"type":"string"},"description":"Filter by tool name"},{"name":"mcp","in":"query","schema":{"type":"string","enum":["only","exclude","true","false"]}},{"name":"errors","in":"query","schema":{"type":"string","enum":["only","exclude","true","false"]}},{"name":"tool_calls","in":"query","schema":{"type":"string","enum":["only"]}},{"name":"steps","in":"query","schema":{"type":"string","enum":["all","multi","single"],"default":"all"},"description":"Filter by single-step or multi-step trace depth."},{"name":"min_steps","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Return traces with at least this many declared or persisted spans. Takes precedence over steps."},{"name":"meaningful","in":"query","schema":{"type":"string","enum":["only","include","rudimentary"],"default":"only"},"description":"Public reads always use only. include and rudimentary are protected forensic scopes requiring PLATPHORM_API_KEY and no-store caching."},{"name":"min_duration","in":"query","schema":{"type":"number","minimum":0}},{"name":"max_duration","in":"query","schema":{"type":"number","minimum":0}},{"name":"date_from","in":"query","schema":{"type":"string"},"description":"Inclusive trace start date or timestamp. Date-only values use UTC calendar days."},{"name":"date_to","in":"query","schema":{"type":"string"},"description":"Inclusive trace start date or timestamp. A date-only value includes that entire UTC calendar day."},{"name":"infrastructure","in":"query","schema":{"type":"string","enum":["include","exclude","only"],"default":"include"},"description":"Include, exclude, or isolate infrastructure within the meaningful-action scope."},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search trace IDs, names, descriptions, agents, models, systems, summaries, tags, and public-safe span text."}],"responses":{"200":{"description":"Meaningful-action trace list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}},"401":{"description":"PLATPHORM_API_KEY required for forensic inclusion of rudimentary records"}}},"post":{"tags":["traces"],"summary":"Create trace","description":"Ingest a new trace. Validated spans are retained for honest parentage and completion, but chronological public listings promote only structurally meaningful actions.","operationId":"createTrace","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTraceRequest"}}}},"responses":{"201":{"description":"Trace created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTraceResponse"}}}},"400":{"description":"Invalid request body"},"429":{"description":"Rate limit exceeded"}}}},"/sessions":{"get":{"tags":["sessions"],"summary":"List sessions","description":"List all unique sessions with aggregated stats","operationId":"listSessions","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Filter by source domain"},{"name":"agent","in":"query","schema":{"type":"string"},"description":"Filter by agent name"}],"responses":{"200":{"description":"List of sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionListResponse"}}}}}}},"/sessions/{sessionId}":{"get":{"tags":["sessions"],"summary":"Get session","description":"Get all traces for a session with optional span data","operationId":"getSession","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include_spans","in":"query","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Session details with traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"404":{"description":"Session not found"}}}},"/traces/{traceId}":{"get":{"tags":["traces"],"summary":"Get trace","description":"Get a meaningful public-safe trace with its redacted spans and evidence. Rudimentary historical traces are not publicly addressable.","operationId":"getTrace","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trace"}}}},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/spans":{"get":{"tags":["spans"],"summary":"List trace spans","description":"List public-safe spans only when the owning trace is a meaningful action.","operationId":"listTraceSpans","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace spans"},"404":{"description":"Trace not found"}}},"post":{"tags":["spans"],"summary":"Append spans","description":"Append spans to a running trace","operationId":"appendSpans","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendSpansRequest"}}}},"responses":{"200":{"description":"Spans appended"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/timeline":{"get":{"tags":["traces"],"summary":"Trace timeline","description":"Build a timestamp-sorted timeline from real public-safe spans.","operationId":"getTraceTimeline","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Timeline view"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/tree":{"get":{"tags":["traces"],"summary":"Trace tree","description":"Build a parent-child tree from span parent relationships.","operationId":"getTraceTree","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tree view"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/waterfall":{"get":{"tags":["traces"],"summary":"Trace waterfall","description":"Build a waterfall view from real span timing.","operationId":"getTraceWaterfall","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Waterfall view"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/service-map":{"get":{"tags":["aggregation"],"summary":"Trace service map","description":"Build public-safe service hop map from source and target span attributes.","operationId":"getTraceServiceMap","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service map"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/critical-path":{"get":{"tags":["aggregation"],"summary":"Trace critical path","description":"Calculate critical path from real public-safe span durations.","operationId":"getTraceCriticalPath","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Critical path"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/completion":{"get":{"tags":["spans"],"summary":"Trace completion","description":"Return recomputable completion state, missing spans, pending spans, late spans, orphan spans, failed spans, and algorithm version.","operationId":"getTraceCompletion","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completion state"},"404":{"description":"Trace not found"}}}},"/traces/{traceId}/complete":{"post":{"tags":["spans"],"summary":"Complete trace","description":"Protected recomputation and persistence of trace completion. Requires PLATPHORM_API_KEY.","operationId":"completeTrace","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completion recomputed"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/traces/{traceId}/expectations":{"post":{"tags":["spans"],"summary":"Declare expected spans","description":"Persist required, optional, or not-applicable span expectations before cross-site execution. Requires PLATPHORM_API_KEY.","operationId":"declareTraceExpectations","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectations"],"properties":{"expectations":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["spanId"],"properties":{"spanId":{"type":"string","maxLength":32},"name":{"type":"string","maxLength":255},"required":{"type":"boolean"},"optional":{"type":"boolean"},"notApplicable":{"type":"boolean"},"deadlineAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true}}}}}}}}},"responses":{"201":{"description":"Expectations persisted and completion recomputed"},"400":{"description":"Invalid expectation declaration"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/start":{"post":{"tags":["spans"],"summary":"Start span","description":"Protected progressive span start. The start must already prove a tool/model action, failure, or PlatPhorm run correlation; otherwise it returns collected=false without writing. A suppressed request boundary returns data.correlationParentSpanId so meaningful children can retain the real upstream action as parent without storing the boundary. Ordinary structured actions should use /spans/batch.","operationId":"startSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Non-meaningful start suppressed without storage"},"201":{"description":"Meaningful span started"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Storage degraded"}}}},"/spans/batch":{"post":{"tags":["spans"],"summary":"Ingest a complete meaningful span batch","description":"Protected bounded ingestion for up to 100 spans. The full topology is validated before writes. Explicit producer semantics are preserved; missing behavior and granularity labels are derived only from real tool/model fields and validated batch parentage. Rudimentary, passive-discovery, and insufficient-action batches return collected=false and are not stored.","operationId":"ingestSpanBatch","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["traceId","spans"],"properties":{"traceId":{"type":"string","maxLength":32},"tags":{"type":"array","items":{"type":"string"}},"spans":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}}}}},"responses":{"200":{"description":"Non-meaningful batch suppressed without storage"},"201":{"description":"Meaningful batch persisted"},"400":{"description":"Invalid or cyclic topology"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/orphans":{"get":{"tags":["spans"],"summary":"List genuine orphan spans","description":"Return public-safe meaningful-action spans whose parent is absent from the same trace. Explicit and safely inferred external entry parents are excluded.","operationId":"listOrphanSpans","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Bounded orphan span readback with an exact total"},"503":{"description":"Storage degraded"}}}},"/spans/complete":{"post":{"tags":["spans"],"summary":"Complete span","description":"Protected span completion and trace lifecycle recomputation.","operationId":"completeSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Span completed"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/fail":{"post":{"tags":["spans"],"summary":"Fail span","description":"Protected span failure and trace lifecycle recomputation.","operationId":"failSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Span failed"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/heartbeat":{"post":{"tags":["spans"],"summary":"Heartbeat span","description":"Protected heartbeat for running spans and async workflows.","operationId":"heartbeatSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Heartbeat recorded"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/annotate":{"post":{"tags":["spans"],"summary":"Annotate span","description":"Protected redacted span annotation. Requires PLATPHORM_API_KEY.","operationId":"annotateSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Span annotated"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/spans/cancel":{"post":{"tags":["spans"],"summary":"Cancel span","description":"Protected span cancellation and trace lifecycle recomputation.","operationId":"cancelSpan","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanLifecycleRequest"}}}},"responses":{"200":{"description":"Span cancelled"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/async/traces":{"post":{"tags":["async"],"summary":"Create async trace","description":"Protected async trace envelope. Returns poll, stream, and completion URLs when durable storage is configured.","operationId":"createAsyncTrace","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncTraceCreateRequest"}}}},"responses":{"201":{"description":"Async trace created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncCreateResponse"}}}},"400":{"description":"Explicit meaningful-action semantics are required"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Storage degraded"}}}},"/async/jobs":{"get":{"tags":["async"],"summary":"List async jobs","operationId":"listAsyncJobs","responses":{"200":{"description":"Public-safe async job list or degraded empty state"}}},"post":{"tags":["async"],"summary":"Create async job","description":"Protected trace-linked async job creation.","operationId":"createAsyncJob","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"responses":{"201":{"description":"Async job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncCreateResponse"}}}},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/jobs":{"get":{"tags":["async"],"summary":"List async jobs","description":"Alias for /async/jobs.","operationId":"listJobs","responses":{"200":{"description":"Public-safe job list or degraded empty state"}}},"post":{"tags":["async"],"summary":"Create async job","description":"Alias for protected /async/jobs creation.","operationId":"createJob","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"responses":{"201":{"description":"Async job created"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/workflows":{"get":{"tags":["workflows"],"summary":"List registered workflow templates","description":"Return real public-safe workflow templates. Templates describe actual handlers and never imply that a protected run has started.","operationId":"listWorkflows","responses":{"200":{"description":"Registered public workflow templates"}}},"post":{"tags":["workflows"],"summary":"Create arbitrary workflow","description":"Arbitrary workflow creation is intentionally unsupported. Use a registered template.","operationId":"createWorkflow","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"responses":{"401":{"description":"PLATPHORM_API_KEY required"},"501":{"description":"Arbitrary workflow creation unsupported"}}}},"/workflows/{id}/run":{"get":{"tags":["workflows"],"summary":"Inspect workflow run contract","operationId":"getWorkflowRunContract","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow template and protected launch usage"},"404":{"description":"Workflow not found"}}},"post":{"tags":["workflows"],"summary":"Launch registered workflow","description":"Start the real 100-step verified platform briefing workflow as a durable trace-linked job. The run publishes, verifies, and creates replayable recovery receipts for unavailable product handoffs. Requires explicit confirmation and PLATPHORM_API_KEY.","operationId":"runWorkflow","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"additionalProperties":false,"properties":{"confirm":{"type":"string","const":"RUN_100_STEP_TRACE"}}}}}},"responses":{"202":{"description":"Trace-linked workflow job accepted"},"400":{"description":"Explicit confirmation missing"},"401":{"description":"PLATPHORM_API_KEY required"},"409":{"description":"A run is already active or preview execution is disabled"},"503":{"description":"Durable trace or job storage unavailable"}}}},"/workflows/{id}/dry-run":{"post":{"tags":["workflows"],"summary":"Validate workflow plan without mutations","description":"Return the exact registered 100-step plan without creating traces, jobs, documents, notes, content, or image artifacts.","operationId":"dryRunWorkflow","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Static plan validated with no mutations"},"401":{"description":"PLATPHORM_API_KEY required"},"404":{"description":"Workflow not found"}}}},"/evidence":{"get":{"tags":["export"],"summary":"List public-safe evidence","description":"List redacted public-safe evidence records.","operationId":"listEvidence","responses":{"200":{"description":"Evidence list"}}},"post":{"tags":["export"],"summary":"Link evidence","description":"Protected evidence linking. Requires PLATPHORM_API_KEY. Raw private evidence is not exposed publicly.","operationId":"linkEvidence","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"responses":{"201":{"description":"Evidence linked"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/search":{"get":{"tags":["traces"],"summary":"Search Trace records","description":"Search meaningful public-safe traces, their spans and evidence, and static playbooks.","operationId":"searchTraceRecords","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results or degraded empty state"}}}},"/observatory":{"get":{"tags":["health"],"summary":"Trace truth model","description":"Homepage truth model with value, source, sourceUrl, fetchedAt, state, and nextAction for every metric.","operationId":"getTraceTruthModel","responses":{"200":{"description":"Trace truth model"}}}},"/observability/journeys":{"get":{"tags":["observability"],"summary":"Observed journey telemetry by system","description":"Report persisted trace membership, span correlation, orphaning, lifecycle, unexpected behavior, and the presence of intent, input, output, evidence, model, prompt, tool, external request, workflow, region, payload, event, behavior, and granularity context. Missing signals remain explicit and are not treated as proof of failure.","operationId":"getJourneyCoverage","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":7}},{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"description":"Filter by observed system identity."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Connected journey coverage or an honest degraded storage result."}}}},"/integrations/status":{"get":{"tags":["network"],"summary":"Network-wide integration status","description":"Graph, sitemap, catalog, and platphorm-* project coverage. Observed means persisted public-safe spans exist; registered, degraded, ambiguous, unmapped, and unknown do not count as connected.","operationId":"getIntegrationStatus","responses":{"200":{"description":"Integration matrix"}}}},"/projects":{"get":{"tags":["network"],"summary":"List PlatPhorm project integrations","description":"Return every checked-out platphorm-* repository, including repository-only projects without a canonical domain. Registry presence is not represented as observed trace execution.","operationId":"listProjectIntegrations","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["observed","registered","degraded","repository_only","unmapped","ambiguous"]}},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Filter by project, canonical domain, or integration slug."}],"responses":{"200":{"description":"Project integration registry"}}}},"/projects/{project}":{"get":{"tags":["network"],"summary":"Get one PlatPhorm project integration","description":"Return canonical mapping, route eligibility, MCP declaration, storage and propagation evidence, plus deterministic next remediation actions.","operationId":"getProjectIntegration","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project integration detail"},"404":{"description":"Project is not present in the checked-out workspace manifest"}}}},"/playbooks":{"get":{"tags":["analysis"],"summary":"Debugging playbooks","description":"Deterministic Trace debugging playbooks with checks, commands, linked tools, and evidence to collect.","operationId":"listDebuggingPlaybooks","responses":{"200":{"description":"Playbook list"}}}},"/reports/trace-summary":{"post":{"tags":["export"],"summary":"Create trace summary report","description":"Create a public-safe report from persisted Trace evidence. Missing evidence is reported as missing, not fabricated.","operationId":"createTraceSummaryReport","responses":{"200":{"description":"Public-safe report"}}}},"/aggregate/summary":{"get":{"tags":["aggregation"],"summary":"Trace aggregate summary","description":"Lifecycle, ingestion, latency, service, propagation, and JA4 hashed/redacted correlation coverage.","operationId":"getAggregateSummary","responses":{"200":{"description":"Aggregate summary"}}}},"/maintenance/trace-names":{"post":{"tags":["aggregation"],"summary":"Repair generic trace titles","description":"Protected, bounded repair of titles that exactly match Trace <traceId>. Candidate titles come only from persisted root or explicitly external entry spans. Dry-run is the default. Requires PLATPHORM_API_KEY.","operationId":"repairGenericTraceNames","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":500,"default":100},"dryRun":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Bounded repair receipt or dry-run preview"},"400":{"description":"Invalid repair bounds"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Storage degraded"}}}},"/maintenance/trace-quality":{"get":{"tags":["aggregation"],"summary":"Audit historical trace quality","description":"Protected, read-only inventory of topology classification drift, aggregate root metadata drift, and stale completion candidates. Requires PLATPHORM_API_KEY.","operationId":"auditHistoricalTraceQuality","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"staleMinutes","in":"query","schema":{"type":"integer","minimum":5,"maximum":10080,"default":15}}],"responses":{"200":{"description":"Exact inventory with bounded samples"},"400":{"description":"Invalid audit bounds"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Storage degraded"}}},"post":{"tags":["aggregation"],"summary":"Repair historical trace quality","description":"Protected, bounded, idempotent repair of inferred distributed roots, genuine orphan classification, aggregate root metadata, and recomputed completion. Requires PLATPHORM_API_KEY and apply=true.","operationId":"repairHistoricalTraceQuality","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apply"],"properties":{"apply":{"type":"boolean","enum":[true]},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25},"staleMinutes":{"type":"integer","minimum":5,"maximum":10080,"default":15},"restoreUpdatedSince":{"type":"string","format":"date-time","description":"Optional lower bound for restoring timestamps changed during a known maintenance window."},"restoreUpdatedBefore":{"type":"string","format":"date-time","description":"Optional exclusive upper bound for restoring timestamps changed during a known maintenance window."}}}}}},"responses":{"200":{"description":"Repair receipt with before and after inventory"},"400":{"description":"Invalid repair confirmation or bounds"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Storage degraded"}}}},"/mcp":{"post":{"tags":["mcp"],"summary":"MCP JSON-RPC endpoint","description":"JSON-RPC 2.0 endpoint supporting initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.","operationId":"mcpJsonRpc","responses":{"200":{"description":"JSON-RPC response"}}}},"/traces/{traceId}/analyze":{"post":{"tags":["analysis"],"summary":"Analyze trace","description":"Run AI analysis on a trace","operationId":"analyzeTrace","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analysis results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisResult"}}}}}}},"/traces/{traceId}/fork":{"post":{"tags":["analysis"],"summary":"Fork trace","description":"Create a time-travel fork from a specific span","operationId":"forkTrace","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkRequest"}}}},"responses":{"201":{"description":"Fork created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkResponse"}}}}}}},"/traces/{traceId}/export":{"get":{"tags":["export"],"summary":"Export trace","description":"Export trace in various formats","operationId":"exportTrace","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown","postmortem","otel"],"default":"json"}},{"name":"plain_english","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Exported trace","content":{"application/json":{},"text/markdown":{}}}}},"post":{"tags":["export"],"summary":"Archive a redacted trace export","description":"Persist one bounded, redacted JSON trace bundle to the private Cloudflare R2 evidence archive. Requires PLATPHORM_API_KEY. The bucket has no public URL.","operationId":"archiveTraceExport","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Redacted trace archive persisted to private R2"},"401":{"description":"PLATPHORM_API_KEY required"},"404":{"description":"Meaningful trace not found"},"413":{"description":"Redacted archive exceeds the bounded size limit"},"503":{"description":"R2 evidence archive unavailable"}}}},"/traces/{traceId}/annotations":{"post":{"tags":["traces"],"summary":"Add annotation","description":"Add a collaborative annotation to a trace","operationId":"addAnnotation","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnnotationRequest"}}}},"responses":{"201":{"description":"Annotation added"}}}},"/traces/compare":{"get":{"tags":["analysis"],"summary":"Compare traces","description":"Compare two traces side-by-side","operationId":"compareTraces","parameters":[{"name":"trace_a","in":"query","required":true,"schema":{"type":"string"}},{"name":"trace_b","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Comparison results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResult"}}}}}}},"/live":{"get":{"tags":["live"],"summary":"Live feed","description":"Get real-time trace feed with network stats","operationId":"getLiveFeed","responses":{"200":{"description":"Live feed data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveFeedResponse"}}}}}}},"/stats":{"get":{"tags":["health"],"summary":"Network stats","description":"Get network-wide statistics","operationId":"getStats","responses":{"200":{"description":"Statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}},"/network/route-compliance/run":{"post":{"tags":["network"],"summary":"Run route compliance probe","description":"Protected bounded route probe for one trusted *.platphormnews.com domain. Results are returned and may be cached ephemerally when durable route-compliance storage is not configured.","operationId":"runRouteComplianceProbe","security":[{"ApiKey":[]},{"PlatphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"domain":{"type":"string"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":10000},"concurrency":{"type":"integer","minimum":1,"maximum":6}},"anyOf":[{"required":["slug"]},{"required":["domain"]}]}}}},"responses":{"202":{"description":"Route probe completed with public-safe route evidence.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or untrusted probe target"},"401":{"description":"PLATPHORM_API_KEY required"}}}}},"components":{"schemas":{"Trace":{"type":"object","properties":{"trace_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"agent_name":{"type":"string","nullable":true},"model_name":{"type":"string","nullable":true},"status":{"type":"string","enum":["running","completed","error","timeout"]},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time","nullable":true},"duration_ms":{"type":"integer","nullable":true},"total_spans":{"type":"integer"},"persisted_span_count":{"type":"integer","description":"Current count of durable span rows."},"span_count_complete":{"type":"boolean","nullable":true,"description":"Whether declared and persisted span counts match."},"total_tool_calls":{"type":"integer"},"prompt_count":{"type":"integer"},"prompt_names":{"type":"array","items":{"type":"string"},"description":"Public-safe prompt identifiers; prompt bodies are not exposed."},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"fingerprint_group":{"type":"string","nullable":true,"description":"Public-safe hashed JA4 digest grouping, never a raw fingerprint."},"has_final_output":{"type":"boolean"},"error_count":{"type":"integer"},"ai_health_score":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"ai_summary":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"}},"annotations":{"type":"array","items":{"$ref":"#/components/schemas/Annotation"}}}},"Span":{"type":"object","properties":{"span_id":{"type":"string"},"parent_span_id":{"type":"string","nullable":true},"name":{"type":"string"},"kind":{"type":"string"},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time","nullable":true},"duration_ms":{"type":"integer","nullable":true},"status":{"type":"string","enum":["ok","error","unset"]},"gen_ai_system":{"type":"string","nullable":true},"gen_ai_operation_name":{"type":"string","nullable":true},"gen_ai_request_model":{"type":"string","nullable":true},"gen_ai_response_model":{"type":"string","nullable":true},"gen_ai_tool_name":{"type":"string","nullable":true},"gen_ai_prompt_name":{"type":"string","nullable":true},"gen_ai_tokens_input":{"type":"integer","nullable":true},"gen_ai_tokens_output":{"type":"integer","nullable":true},"gen_ai_tool_call_arguments":{"type":"object","nullable":true},"gen_ai_tool_call_result":{"type":"object","nullable":true},"events":{"type":"array","items":{"type":"object"}},"links":{"type":"array","items":{"type":"object"}}}},"SpanLifecycleRequest":{"type":"object","required":["traceId"],"properties":{"traceId":{"type":"string","description":"Trace ID or W3C trace ID."},"spanId":{"type":"string","description":"Span ID. W3C span IDs are accepted."},"parentSpanId":{"type":"string","nullable":true},"name":{"type":"string"},"kind":{"type":"string","enum":["internal","server","client","producer","consumer","tool","api","browser","sandbox","eval","agent","workflow"]},"sourceSite":{"type":"string"},"targetSite":{"type":"string"},"serviceName":{"type":"string"},"toolName":{"type":"string"},"apiOperation":{"type":"string"},"genAiSystem":{"type":"string"},"genAiOperationName":{"type":"string"},"requestModel":{"type":"string"},"responseModel":{"type":"string"},"promptName":{"type":"string","description":"Prompt identifier only; do not send secrets."},"inputTokens":{"type":"integer","minimum":0},"outputTokens":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending","started","completed","failed","cancelled","timed_out","late","orphaned","degraded","unknown","ok","error"],"description":"Lifecycle status. OTel ok/error aliases are normalized to completed/failed."},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"deadlineAt":{"type":"string","format":"date-time"},"heartbeatAt":{"type":"string","format":"date-time"},"isExpected":{"type":"boolean"},"isOptional":{"type":"boolean"},"isLate":{"type":"boolean"},"metadata":{"type":"object","description":"Redacted before public display. Do not include secrets."}}},"TraceCompletion":{"type":"object","properties":{"completionStatus":{"type":"string","enum":["pending","active","waiting_for_spans","partially_complete","completed","failed","cancelled","timed_out","degraded","orphaned","unknown"]},"reason":{"type":"string"},"algorithmVersion":{"type":"string"},"expectedSpans":{"type":"array","items":{"type":"string"}},"missingSpans":{"type":"array","items":{"type":"string"}},"lateSpans":{"type":"array","items":{"type":"string"}},"orphanSpans":{"type":"array","items":{"type":"string"}},"failedSpans":{"type":"array","items":{"type":"string"}}}},"AsyncTraceCreateRequest":{"type":"object","required":["name","intent","input"],"properties":{"traceId":{"type":"string","description":"Optional caller-supplied trace identifier."},"name":{"type":"string","minLength":1,"maxLength":255},"intent":{"type":"string","minLength":1,"maxLength":1000,"description":"Explicit public-safe purpose of the async action."},"input":{"type":"string","minLength":1,"maxLength":1000,"description":"Bounded public-safe input summary; never include secrets."},"summary":{"type":"string","nullable":true},"sourceSite":{"type":"string","nullable":true},"targetSite":{"type":"string","nullable":true},"deadlineAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","description":"Additional redacted public-safe metadata."}}},"AsyncCreateResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","claimed","running","waiting","completed","failed","cancelled","timed_out","degraded"]},"traceId":{"type":"string"},"pollUrl":{"type":"string"},"streamUrl":{"type":"string"},"completionUrl":{"type":"string"},"expiresAt":{"type":"string","nullable":true}}}}},"Annotation":{"type":"object","properties":{"id":{"type":"string"},"span_id":{"type":"string","nullable":true},"author_name":{"type":"string"},"content":{"type":"string"},"annotation_type":{"type":"string","enum":["comment","issue","suggestion","ai_generated"]},"is_resolved":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Session":{"type":"object","properties":{"session_id":{"type":"string"},"source_domain":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"last_activity":{"type":"string","format":"date-time","nullable":true},"stats":{"$ref":"#/components/schemas/SessionStats"},"agents":{"type":"array","items":{"type":"string"}},"models":{"type":"array","items":{"type":"string"}}}},"SessionStats":{"type":"object","properties":{"trace_count":{"type":"integer"},"total_spans":{"type":"integer"},"total_tool_calls":{"type":"integer"},"total_tokens":{"type":"integer"},"total_errors":{"type":"integer"},"avg_health_score":{"type":"integer","nullable":true},"status_breakdown":{"type":"object","properties":{"running":{"type":"integer"},"completed":{"type":"integer"},"error":{"type":"integer"},"timeout":{"type":"integer"}}}}},"SessionListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"SessionResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/Session"},"stats":{"$ref":"#/components/schemas/SessionStats"},"traces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"CreateTraceRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"sourceDomain":{"type":"string","description":"PlatPhorm source domain."},"agentName":{"type":"string"},"modelName":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["running","completed","error","timeout"],"default":"running"},"spans":{"type":"array","description":"The complete batch is persisted only when its structure proves a meaningful action; otherwise no trace envelope or span rows are written.","items":{"$ref":"#/components/schemas/CreateSpanRequest"}},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}},"CreateSpanRequest":{"type":"object","required":["spanId","name","startTime"],"properties":{"spanId":{"type":"string","maxLength":32},"parentSpanId":{"type":"string","nullable":true,"maxLength":32},"name":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"kind":{"type":"string","default":"INTERNAL"},"attributes":{"type":"object","description":"OpenTelemetry attributes including gen_ai.*, mcp.*, service, intent, input, output, and evidence context. Public data is redacted before storage and display."},"events":{"type":"array","items":{"type":"object"}},"links":{"type":"array","items":{"type":"object"}},"status":{"type":"string","enum":["ok","error","unset"],"default":"unset"},"errorMessage":{"type":"string"}}},"CreateTraceResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"trace_id":{"type":"string"},"collected":{"type":"boolean","description":"True only when durable or explicitly reported fallback storage accepted the meaningful action."},"share_token":{"type":"string"},"share_url":{"type":"string"},"status":{"type":"string"},"spans_ingested":{"type":"integer","description":"Span rows persisted from a structurally meaningful action batch."},"spans_received":{"type":"integer","description":"Total spans accepted in the request payload."},"spans_skipped":{"type":"integer","description":"Spans accepted but intentionally not persisted as durable span rows."},"span_persistence_policy":{"type":"string"},"span_persistence_reason":{"type":"string"},"assessment_reason":{"type":"string","description":"Structural reason for persistence or suppression."},"correlationParentSpanId":{"type":"string","nullable":true,"description":"Upstream meaningful action parent returned when a request boundary is suppressed."}}}}},"TraceListResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer","nullable":true},"total_is_exact":{"type":"boolean"},"total_pages":{"type":"integer","nullable":true},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}},"AppendSpansRequest":{"type":"object","required":["spans"],"properties":{"spans":{"type":"array","items":{"$ref":"#/components/schemas/CreateSpanRequest"}}}},"ForkRequest":{"type":"object","required":["span_id"],"properties":{"span_id":{"type":"string"},"changes":{"type":"object","properties":{"arguments":{"type":"object"}}}}},"ForkResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"fork_id":{"type":"string"},"forked_trace_id":{"type":"string"},"comparison_url":{"type":"string"}}}}},"AnalysisResult":{"type":"object","properties":{"health_score":{"type":"integer","minimum":0,"maximum":100},"summary":{"type":"string"},"anomalies":{"type":"array","items":{"type":"object"}},"suggestions":{"type":"array","items":{"type":"string"}},"network_percentile":{"type":"integer"}}},"CompareResult":{"type":"object","properties":{"trace_a":{"$ref":"#/components/schemas/Trace"},"trace_b":{"$ref":"#/components/schemas/Trace"},"differences":{"type":"array","items":{"type":"object"}},"summary":{"type":"string"}}},"CreateAnnotationRequest":{"type":"object","required":["content","author_name"],"properties":{"span_id":{"type":"string"},"author_name":{"type":"string"},"content":{"type":"string"},"annotation_type":{"type":"string","enum":["comment","issue","suggestion"],"default":"comment"}}},"LiveFeedResponse":{"type":"object","properties":{"traces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"stats":{"type":"object","properties":{"active_traces":{"type":"integer"},"traces_per_minute":{"type":"number"},"avg_health_score":{"type":"number"},"error_rate":{"type":"number"}}}}},"StatsResponse":{"type":"object","properties":{"network":{"type":"object","properties":{"total_sites":{"type":"integer"},"mcp_enabled_sites":{"type":"integer"},"tools":{"type":"integer"},"resources":{"type":"integer"},"prompts":{"type":"integer"}}},"traces":{"type":"object","properties":{"total":{"type":"integer"},"today":{"type":"integer"},"avg_health_score":{"type":"number"},"avg_duration_ms":{"type":"number"}}}}}},"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Protected actions use Authorization: Bearer $PLATPHORM_API_KEY"},"PlatphormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Protected actions may also use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"}}},"security":[{},{"ApiKey":[]}]}