{"openapi":"3.1.0","info":{"title":"COBOL AI API","version":"0.0.1","description":"COBOL AI is the public-safe COBOL modernization, deterministic static analysis, compliance review, documentation generation, COBOL 2023 suggestion, cost estimation, Kanban preview, ASCII rendering, and MCP/API layer for cobol.platphormnews.com. Model-backed translation and external mutations are scaffolded as future protected actions and use PLATPHORM_API_KEY when enforcement is enabled.","contact":{"name":"PlatPhormNews","url":"https://platphormnews.com"}},"servers":[{"url":"https://cobol.platphormnews.com","description":"Production"}],"security":[],"components":{"securitySchemes":{"PlatPhormBearer":{"type":"http","scheme":"bearer","description":"Future protected actions accept Authorization: Bearer $PLATPHORM_API_KEY when PLATPHORM_REQUIRE_API_KEY=true."},"PlatPhormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Future protected actions accept X-PlatPhorm-API-Key: $PLATPHORM_API_KEY when PLATPHORM_REQUIRE_API_KEY=true."}}},"tags":[{"name":"health","description":"Public health and route compliance status"},{"name":"cobol","description":"COBOL static analysis and modernization helpers"},{"name":"integrations","description":"Kanban, ASCII, jobs, and report integrations with honest degraded states"},{"name":"discovery","description":"OpenAPI, llms, RSS, sitemap, well-known, and MCP discovery"},{"name":"mcp","description":"JSON-RPC 2.0 MCP endpoint"}],"paths":{"/api/health":{"get":{"tags":["health"],"summary":"Get COBOL AI health","description":"Returns valid public-safe health JSON with auth policy, model state, discovery state, trace state, and dependency degradation.","security":[],"responses":{"200":{"description":"Health payload"}}}},"/api/v1/health":{"get":{"tags":["health"],"summary":"Health alias","security":[],"responses":{"200":{"description":"Health payload"}}}},"/api/analyze":{"post":{"summary":"Analyze COBOL deterministically","description":"Runs deterministic COBOL static analysis without model calls. Returns complexity score, risk findings, data dictionary evidence, and cost estimate.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/analyze":{"post":{"summary":"Analyze COBOL deterministically","description":"V1 alias for /api/analyze.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/modernize":{"post":{"summary":"Modernize or translate COBOL","description":"Streams deterministic compliance/documentation/COBOL 2023 suggestions or model-assisted translation when a backend model is configured. When no model is configured, returns an explicit degraded response instead of fake translated code.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","maxLength":50000},"targetLanguage":{"type":"string","enum":["java","python","typescript","csharp","cobol"],"default":"typescript"},"mode":{"type":"string","enum":["translate","compliance","document","cobol2023"],"default":"translate"}}}}}},"responses":{"200":{"description":"text/plain stream or degraded plain-text response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/modernize":{"post":{"summary":"Modernize or translate COBOL","description":"V1 alias for /api/modernize.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/compliance":{"post":{"summary":"Run deterministic COBOL compliance review","description":"Returns deterministic compliance findings and summary.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/document":{"post":{"summary":"Generate deterministic COBOL documentation","description":"Returns markdown documentation derived from source structure.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/cobol2023":{"post":{"summary":"Suggest COBOL 2023 modernization","description":"Returns experimental deterministic suggestions requiring human review.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/cost-estimate":{"post":{"summary":"Estimate modernization cost","description":"Returns deterministic per-line cost estimate and assumptions.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/data-dictionary":{"post":{"summary":"Extract COBOL data dictionary","description":"Returns data items, PIC clauses, inferred types, and risk hints.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/ascii":{"post":{"summary":"Render COBOL as ASCII","description":"Returns bounded local ASCII rendering and upstream integration state.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/v1/ascii":{"post":{"summary":"Render COBOL as ASCII","description":"V1 alias for /api/ascii.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Public-safe operation response"},"400":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}},"413":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-public-access":"public-safe"}},"/api/kanban":{"get":{"tags":["integrations"],"summary":"Get Kanban integration state","security":[],"responses":{"200":{"description":"Public Kanban degradation/preview state"}}},"post":{"tags":["integrations"],"summary":"Create Kanban tracking preview","description":"Public Phase 1 returns a local Kanban task preview by default. External Kanban mutation is a future protected action using PLATPHORM_API_KEY when enforcement and mutation are enabled.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cobolCode"],"properties":{"cobolCode":{"type":"string","minLength":1,"maxLength":50000,"description":"COBOL source code. COBOL AI does not persist source code server-side by default."}}}}}},"responses":{"200":{"description":"Local Kanban preview"},"401":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-future-protected":true}},"/api/jobs":{"post":{"tags":["integrations"],"summary":"Generate public-safe job draft","description":"Returns a deterministic local job draft. Publishing to jobs.platphormnews.com is not performed in Phase 1 and is a future protected action using PLATPHORM_API_KEY.","security":[],"responses":{"200":{"description":"Local job draft with degraded publication state"},"401":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}},"x-future-protected":true}},"/api/v1/samples":{"get":{"tags":["cobol"],"summary":"List COBOL samples","security":[],"responses":{"200":{"description":"Sample index and sample source"}}}},"/api/v1/pricing":{"get":{"tags":["cobol"],"summary":"List pricing tiers","security":[],"responses":{"200":{"description":"Deterministic cost tiers"}}}},"/api/mcp":{"get":{"tags":["mcp"],"summary":"Read MCP metadata","description":"Public read-only MCP introspection.","security":[],"responses":{"200":{"description":"MCP metadata, tools, resources, and prompts"}}},"post":{"tags":["mcp"],"summary":"Call MCP JSON-RPC 2.0 method","description":"Supports initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get. Tools: modernize_cobol, analyze_cobol, check_cobol_compliance, generate_cobol_docs, suggest_cobol2023, estimate_cobol_cost, extract_data_dictionary, create_kanban_task, convert_to_ascii, list_samples, get_pricing, get_health, get_info, get_route_compliance, get_discovery_compliance, create_docs_report, create_sheet_report, create_deck_summary.","security":[],"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}},"/api/cron/refresh":{"get":{"tags":["discovery"],"summary":"Bounded metadata refresh cron","description":"Protected by PLATPHORM_API_KEY when enforcement is enabled or Vercel Cron context. Refresh is idempotent and reports degraded state without publishing dead links.","security":[{"PlatPhormBearer":[]},{"PlatPhormApiKey":[]}],"responses":{"200":{"description":"Refresh summary"},"401":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}}},"post":{"tags":["discovery"],"summary":"Bounded metadata refresh cron","security":[{"PlatPhormBearer":[]},{"PlatPhormApiKey":[]}],"responses":{"200":{"description":"Refresh summary"},"401":{"description":"Standard error response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["ok","error"]}}}}}}},"/api/docs":{"get":{"tags":["discovery"],"summary":"OpenAPI JSON","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}},"/openapi.json":{"get":{"tags":["discovery"],"summary":"OpenAPI JSON","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}},"/openapi.yaml":{"get":{"tags":["discovery"],"summary":"OpenAPI YAML","security":[],"responses":{"200":{"description":"OpenAPI 3.1 YAML"}}}}},"x-auth-policy":{"platformKey":"PLATPHORM_API_KEY","defaultPhase1":"public-safe","enforcementFlag":"PLATPHORM_REQUIRE_API_KEY"}}