{
  "openapi": "3.1.0",
  "info": {
    "title": "signal:// ASCII API",
    "version": "0.3.0",
    "description": "Convert images into ASCII/ANSI art with a physically-accurate pipeline: linear-light perceptual luminance, percentile auto-levels, unsharp-mask detail enhancement, contour-aware structural glyphs, optional Sobel edge line-art, and Floyd–Steinberg dithering. The live studio adds an adaptive temporal filter for flicker-free video."
  },
  "servers": [
    {
      "url": "https://v2a.platphormnews.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Liveness + capability probe",
        "description": "Accepts W3C traceparent/tracestate and returns the accepted or generated public-safe trace context in response headers.",
        "responses": {
          "200": {
            "description": "Service healthy"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Versioned liveness and capability probe",
        "description": "Returns the same public-safe, trace-aware health envelope as /api/health.",
        "responses": {
          "200": {
            "description": "Service healthy"
          }
        }
      }
    },
    "/api/v1/render": {
      "post": {
        "summary": "Render an image to ASCII/ANSI/HTML/JSON/SVG",
        "description": "Accepts multipart/form-data (field `image`) or JSON ({ imageUrl } or { imageBase64 }). Render params may be passed as query string, form fields, or JSON keys. The server accepts W3C trace context and exports a public-safe render lifecycle when PLATPHORM_API_KEY is configured.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "image": {
                    "type": "string",
                    "format": "binary"
                  },
                  "columns": {
                    "type": "integer",
                    "description": "Output width in characters."
                  },
                  "charset": {
                    "type": "string",
                    "description": "One of: standard, detailed, blocks, binary, dots, minimal."
                  },
                  "format": {
                    "type": "string",
                    "description": "text | ansi | html | json | json-compact | svg."
                  },
                  "color": {
                    "type": "boolean",
                    "description": "Per-cell 24-bit color (ignored by plain text)."
                  },
                  "invert": {
                    "type": "boolean",
                    "description": "Invert luminance mapping."
                  },
                  "contrast": {
                    "type": "number",
                    "description": "Tonal contrast multiplier."
                  },
                  "brightness": {
                    "type": "number",
                    "description": "Luminance offset."
                  },
                  "saturation": {
                    "type": "number",
                    "description": "Color-mode saturation boost."
                  },
                  "gamma": {
                    "type": "number",
                    "description": "Perceptual midtone response."
                  },
                  "edges": {
                    "type": "boolean",
                    "description": "Sobel edge-detection line-art mode."
                  },
                  "edgeStrength": {
                    "type": "number",
                    "description": "Edge magnitude multiplier."
                  },
                  "dither": {
                    "type": "boolean",
                    "description": "Floyd–Steinberg error diffusion."
                  },
                  "sharpen": {
                    "type": "number",
                    "description": "Unsharp-mask detail enhancement."
                  },
                  "autoLevels": {
                    "type": "number",
                    "description": "Automatic percentile histogram stretch."
                  },
                  "structure": {
                    "type": "number",
                    "description": "Contour-aware directional glyph substitution ( - / | \\ )."
                  },
                  "denoise": {
                    "type": "number",
                    "description": "Edge-preserving bilateral denoising before detail recovery."
                  },
                  "motionSensitivity": {
                    "type": "number",
                    "description": "Motion responsiveness in the final Bayesian posterior update."
                  },
                  "autoOptimize": {
                    "type": "number",
                    "description": "Strength of source-aware Auto Director tuning against the selected quality rubric."
                  },
                  "qualityTarget": {
                    "type": "string",
                    "description": "balanced | portrait | motion | low-light | round-trip."
                  },
                  "glyphStrategy": {
                    "type": "string",
                    "description": "adaptive chooses the smallest glyph codebook under maxGlyphRmse; fixed preserves the selected ramp."
                  },
                  "maxGlyphRmse": {
                    "type": "number",
                    "description": "Maximum normalized luminance quantization RMSE for adaptive glyph selection."
                  },
                  "monoColor": {
                    "type": "string",
                    "description": "Color for mono/ansi/svg/html output."
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "imageUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "HTTPS URL on a trusted host or an explicitly configured V2A_IMAGE_FETCH_ALLOWLIST host."
                  },
                  "imageBase64": {
                    "type": "string"
                  },
                  "columns": {
                    "type": "integer",
                    "description": "Output width in characters."
                  },
                  "charset": {
                    "type": "string",
                    "description": "One of: standard, detailed, blocks, binary, dots, minimal."
                  },
                  "format": {
                    "type": "string",
                    "description": "text | ansi | html | json | json-compact | svg."
                  },
                  "color": {
                    "type": "boolean",
                    "description": "Per-cell 24-bit color (ignored by plain text)."
                  },
                  "invert": {
                    "type": "boolean",
                    "description": "Invert luminance mapping."
                  },
                  "contrast": {
                    "type": "number",
                    "description": "Tonal contrast multiplier."
                  },
                  "brightness": {
                    "type": "number",
                    "description": "Luminance offset."
                  },
                  "saturation": {
                    "type": "number",
                    "description": "Color-mode saturation boost."
                  },
                  "gamma": {
                    "type": "number",
                    "description": "Perceptual midtone response."
                  },
                  "edges": {
                    "type": "boolean",
                    "description": "Sobel edge-detection line-art mode."
                  },
                  "edgeStrength": {
                    "type": "number",
                    "description": "Edge magnitude multiplier."
                  },
                  "dither": {
                    "type": "boolean",
                    "description": "Floyd–Steinberg error diffusion."
                  },
                  "sharpen": {
                    "type": "number",
                    "description": "Unsharp-mask detail enhancement."
                  },
                  "autoLevels": {
                    "type": "number",
                    "description": "Automatic percentile histogram stretch."
                  },
                  "structure": {
                    "type": "number",
                    "description": "Contour-aware directional glyph substitution ( - / | \\ )."
                  },
                  "denoise": {
                    "type": "number",
                    "description": "Edge-preserving bilateral denoising before detail recovery."
                  },
                  "motionSensitivity": {
                    "type": "number",
                    "description": "Motion responsiveness in the final Bayesian posterior update."
                  },
                  "autoOptimize": {
                    "type": "number",
                    "description": "Strength of source-aware Auto Director tuning against the selected quality rubric."
                  },
                  "qualityTarget": {
                    "type": "string",
                    "description": "balanced | portrait | motion | low-light | round-trip."
                  },
                  "glyphStrategy": {
                    "type": "string",
                    "description": "adaptive chooses the smallest glyph codebook under maxGlyphRmse; fixed preserves the selected ramp."
                  },
                  "maxGlyphRmse": {
                    "type": "number",
                    "description": "Maximum normalized luminance quantization RMSE for adaptive glyph selection."
                  },
                  "monoColor": {
                    "type": "string",
                    "description": "Color for mono/ansi/svg/html output."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rendered output (content-type varies by `format`)."
          },
          "400": {
            "description": "Bad request / no image supplied."
          },
          "413": {
            "description": "Image exceeds size limit."
          }
        }
      }
    },
    "/api/v1/a2v-handoff": {
      "get": {
        "summary": "Trusted A2V handoff manifest",
        "description": "Public-safe browser handoff contract for streaming V2A video/webcam ASCII frames to https://a2v.platphormnews.com by fixed-origin window.postMessage. Backend async status checks use PLATPHORM_API_KEY when configured.",
        "responses": {
          "200": {
            "description": "Trusted A2V handoff metadata and message protocol."
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "summary": "Model Context Protocol endpoint (JSON-RPC 2.0)",
        "description": "Implements the canonical discovery methods plus single and bounded-batch tools/call for `render_ascii`. Tool executions export measured spans and linked evidence after redaction when Trace is configured.",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PlatPhormBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "PLATPHORM_API_KEY for protected platform actions. This release exposes no public mutation."
      },
      "PlatPhormHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "PLATPHORM_API_KEY for protected platform actions. This release exposes no public mutation."
      }
    }
  }
}