{"openapi":"3.1.0","info":{"title":"MCP Trace Observatory API","version":"0.0.2","description":"AI-First observability API for MCP agents. Ingest, analyze, and visualize AI agent behavior.","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 management within traces"},{"name":"analysis","description":"AI-powered trace analysis"},{"name":"export","description":"Trace export and sharing"},{"name":"live","description":"Real-time trace streaming"},{"name":"health","description":"API health and status"}],"paths":{"/traces":{"get":{"tags":["traces"],"summary":"List traces","description":"List all public traces with optional filtering","operationId":"listTraces","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"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":"tag","in":"query","schema":{"type":"string"},"description":"Filter by tag"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search name/description"}],"responses":{"200":{"description":"List of traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}}}},"post":{"tags":["traces"],"summary":"Create trace","description":"Ingest a new trace with spans","operationId":"createTrace","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 trace with all spans, annotations, and forks","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":{"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}/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":{}}}}}},"/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"}}}}}}}},"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"},"total_tool_calls":{"type":"integer"},"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_tool_name":{"type":"string","nullable":true},"gen_ai_tool_call_arguments":{"type":"object","nullable":true},"gen_ai_tool_call_result":{"type":"object","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","startTime"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"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","items":{"$ref":"#/components/schemas/CreateSpanRequest"}},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}},"CreateSpanRequest":{"type":"object","required":["name","startTime"],"properties":{"name":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"kind":{"type":"string","default":"INTERNAL"},"genAiToolName":{"type":"string"},"genAiToolCallArguments":{"type":"object"},"genAiToolCallResult":{"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"},"share_token":{"type":"string"},"share_url":{"type":"string"},"status":{"type":"string"},"spans_ingested":{"type":"integer"}}}}},"TraceListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"traces":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}},"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":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for elevated rate limits"}}},"security":[{},{"ApiKey":[]}]}