{"openapi":"3.1.0","info":{"title":"Spec Workbench API","description":"AI-first API spec workbench. Parse, validate, diff, and generate code from OpenAPI, AsyncAPI, JSON Schema, and MCP specs.","version":"0.1.0","contact":{"name":"PlatPhorm News","url":"https://platphormnews.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://platphorm-spec-workbench-qz70kq920-ph3ar.vercel.app","description":"Current environment"}],"tags":[{"name":"health","description":"Health check endpoints"},{"name":"specs","description":"Spec management endpoints"},{"name":"templates","description":"Template library endpoints"},{"name":"generate","description":"Code generation endpoints"},{"name":"traces","description":"Observability and trace endpoints (via trace.platphormnews.com)"},{"name":"network","description":"Platphorm News network status"}],"paths":{"/api/health":{"get":{"tags":["health"],"summary":"Health check","description":"Returns the health status of the service","operationId":"getHealth","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Service is degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/specs":{"get":{"tags":["specs"],"summary":"List specs","description":"Returns a list of saved specs","operationId":"listSpecs","parameters":[{"name":"type","in":"query","description":"Filter by spec type","schema":{"type":"string","enum":["openapi","asyncapi","jsonschema","mcp"]}},{"name":"limit","in":"query","description":"Maximum number of results","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of specs","content":{"application/json":{"schema":{"type":"object","properties":{"specs":{"type":"array","items":{"$ref":"#/components/schemas/Spec"}},"total":{"type":"integer"}}}}}}}},"post":{"tags":["specs"],"summary":"Create spec","description":"Parse and save a new spec","operationId":"createSpec","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpecInput"}}}},"responses":{"201":{"description":"Spec created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Spec"}}}},"400":{"description":"Invalid spec","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/specs/{id}/validate":{"post":{"tags":["specs"],"summary":"Validate spec","description":"Validate a spec and return issues","operationId":"validateSpec","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/specs/{id}/repair":{"post":{"tags":["specs"],"summary":"Repair spec","description":"Auto-repair common issues in a spec","operationId":"repairSpec","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Repair result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairResult"}}}}}}},"/api/v1/specs/{id}/generate/mcp":{"post":{"tags":["generate"],"summary":"Generate MCP server","description":"Generate a full MCP server scaffold from a spec","operationId":"generateMcpServer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpGeneratorConfig"}}}},"responses":{"200":{"description":"Generated MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResult"}}}}}}},"/api/v1/templates":{"get":{"tags":["templates"],"summary":"List templates","description":"Returns the template library","operationId":"listTemplates","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["openapi","asyncapi","jsonschema","mcp"]}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of templates","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}}}}},"/api/v1/traces":{"get":{"tags":["traces"],"summary":"List traces","description":"List AI agent traces from the Trace Observatory. Proxies to trace.platphormnews.com","operationId":"listTraces","parameters":[{"name":"limit","in":"query","description":"Max traces to return","schema":{"type":"integer","default":20,"maximum":100}},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["running","completed","error","timeout"]}},{"name":"agent","in":"query","description":"Filter by agent name","schema":{"type":"string"}},{"name":"minHealth","in":"query","description":"Minimum AI health score (0-100)","schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"List of traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceList"}}}}}}},"/api/v1/traces/{traceId}":{"get":{"tags":["traces"],"summary":"Get trace details","description":"Get detailed information about a specific trace including spans and tool calls","operationId":"getTrace","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceDetail"}}}},"404":{"description":"Trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/network":{"get":{"tags":["network"],"summary":"Get network status","description":"Get status of the Platphorm News MCP network including all federated servers","operationId":"getNetworkStatus","responses":{"200":{"description":"Network status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkStatus"}}}}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"service":{"type":"string"},"version":{"type":"string"},"environment":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string"},"latency_ms":{"type":"integer"}}}},"latency_ms":{"type":"integer"}}},"Spec":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string","enum":["openapi","asyncapi","jsonschema","mcp"]},"version":{"type":"string"},"is_valid":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SpecInput":{"type":"object","required":["content"],"properties":{"name":{"type":"string"},"content":{"type":"string"},"type":{"type":"string","enum":["openapi","asyncapi","jsonschema","mcp"]}}},"ValidationResult":{"type":"object","properties":{"isValid":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"info":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}}}},"ValidationIssue":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]}}},"RepairResult":{"type":"object","properties":{"wasRepaired":{"type":"boolean"},"changes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}}}},"repairedContent":{"type":"string"}}},"GenerationResult":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"},"language":{"type":"string"},"size":{"type":"integer"}}}},"summary":{"type":"string"},"totalFiles":{"type":"integer"},"totalSize":{"type":"integer"}}},"McpGeneratorConfig":{"type":"object","properties":{"serviceName":{"type":"string"},"includeStdio":{"type":"boolean","default":true},"includeHttp":{"type":"boolean","default":true},"includePlatphormIdentity":{"type":"boolean","default":true}}},"Template":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["openapi","asyncapi","jsonschema","mcp"]},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"is_featured":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"TraceList":{"type":"object","properties":{"traces":{"type":"array","items":{"$ref":"#/components/schemas/TraceItem"}}}},"TraceItem":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","completed","error","timeout"]},"agent":{"type":"string"},"healthScore":{"type":"integer","minimum":0,"maximum":100},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"spanCount":{"type":"integer"}}},"TraceDetail":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"agent":{"type":"string"},"healthScore":{"type":"integer"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"spans":{"type":"array","items":{"$ref":"#/components/schemas/TraceSpan"}},"toolCalls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}},"metadata":{"type":"object"}}},"TraceSpan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"attributes":{"type":"object"}}},"ToolCall":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"input":{"type":"object"},"output":{"type":"object"},"duration":{"type":"integer"},"error":{"type":"string"}}},"NetworkStatus":{"type":"object","properties":{"name":{"type":"string"},"hub":{"type":"string"},"totalSites":{"type":"integer"},"mcpServers":{"type":"integer"},"totalTools":{"type":"integer"},"servers":{"type":"array","items":{"$ref":"#/components/schemas/NetworkServer"}}}},"NetworkServer":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["online","offline","degraded"]},"tools":{"type":"integer"},"latency":{"type":"integer"}}}}}}