openapi: "3.1.0"
info: 
  title: "COBOL AI API"
  version: "0.6.0"
  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"