openapi: "3.1.0"
info:
  title: "signal:// a2v — ASCII-to-video API"
  version: "1.0.0"
  description: "A2V takes ASCII / ANSI / asciicast / JSON frame-stream art and reconstructs it into animated browser video. The browser studio can also accept trusted source-artifact handoffs for source-quality playback; this stateless HTTP API renders a selected ASCII frame as SVG, HTML, ANSI, JSON, or text, or emits every parsed frame as canonical NDJSON with format=json-stream."
servers:
  - url: "https://platphorm-a2v-7z8cox59v-platphormnews.vercel.app"
components:
  securitySchemes:
    PlatPhormBearer:
      type: "http"
      scheme: "bearer"
      description: "Use Authorization: Bearer $PLATPHORM_API_KEY for protected PlatPhorm actions."
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Alternative PLATPHORM_API_KEY header for protected PlatPhorm actions."
paths:
  "/api/health":
    get:
      summary: "Liveness + capability probe"
      responses:
        200:
          description: "Service healthy"
  "/api/v1/health":
    get:
      summary: "Versioned liveness + platform contract probe"
      responses:
        200:
          description: "Service healthy"
  "/api/docs":
    get:
      summary: "Machine-readable API and platform route documentation"
      responses:
        200:
          description: "Docs payload"
  "/api/v1/render":
    post:
      summary: "Render ASCII art to SVG/HTML/ANSI/JSON/NDJSON/text"
      description: "Accepts the art as JSON ({ ascii } or trusted { asciiUrl } or { asciiBase64 }), multipart/form-data (field `ascii` file), or a raw text/plain body. Multi-frame ( --- / === separated), asciicast .cast, JSON frame arrays, and NDJSON frame streams are supported; pick a frame with `frame`, or request format=json-stream to return every parsed frame as canonical NDJSON. WebM/source-quality restoration is handled by the browser studio via upload or trusted handoff payloads."
      requestBody:
        required: true
        content:
          "text/plain":
            schema:
              type: "string"
          "multipart/form-data":
            schema:
              type: "object"
              properties:
                ascii:
                  type: "string"
                  format: "binary"
                format:
                  type: "string"
                  description: "svg | html | ansi | json | json-stream | text output artifact."
                monoColor:
                  type: "string"
                  description: "Phosphor / glyph color."
                background:
                  type: "string"
                  description: "Backdrop color (svg/html)."
                glow:
                  type: "number"
                  description: "CRT phosphor bloom amount (svg/html)."
                scanlines:
                  type: "boolean"
                  description: "Overlay CRT scanlines (svg/html)."
                fontSize:
                  type: "integer"
                  description: "Cell height in px (svg/html)."
                gradientTo:
                  type: "string"
                  description: "Optional top→bottom gradient target color."
                frame:
                  type: "integer"
                  description: "Frame index for multi-frame / .cast input."
                trim:
                  type: "boolean"
                  description: "Trim blank border rows and columns."
          "application/json":
            schema:
              type: "object"
              properties:
                ascii:
                  type: "string"
                asciiUrl:
                  type: "string"
                  description: "Trusted https URL on A2V/asciicast/PlatPhormNews domains only."
                asciiBase64:
                  type: "string"
                format:
                  type: "string"
                  description: "svg | html | ansi | json | json-stream | text output artifact."
                monoColor:
                  type: "string"
                  description: "Phosphor / glyph color."
                background:
                  type: "string"
                  description: "Backdrop color (svg/html)."
                glow:
                  type: "number"
                  description: "CRT phosphor bloom amount (svg/html)."
                scanlines:
                  type: "boolean"
                  description: "Overlay CRT scanlines (svg/html)."
                fontSize:
                  type: "integer"
                  description: "Cell height in px (svg/html)."
                gradientTo:
                  type: "string"
                  description: "Optional top→bottom gradient target color."
                frame:
                  type: "integer"
                  description: "Frame index for multi-frame / .cast input."
                trim:
                  type: "boolean"
                  description: "Trim blank border rows and columns."
      responses:
        200:
          description: "Rendered output (content-type varies by `format`; json-stream returns application/x-ndjson)."
          headers:
            traceparent:
              description: "W3C context for the A2V server span."
              schema:
                type: "string"
            X-PlatPhorm-Trace-Id:
              description: "Canonical 32-character trace identifier."
              schema:
                type: "string"
            X-PlatPhorm-Trace-Url:
              description: "Trace debugger URL for this operation."
              schema:
                type: "string"
                format: "uri"
            X-PlatPhorm-Trace-Export:
              description: "Trace export state: connected, degraded, or disabled."
              schema:
                type: "string"
        400:
          description: "Bad request / no ASCII supplied."
        413:
          description: "Payload exceeds size limit."
  "/api/mcp":
    post:
      summary: "Model Context Protocol endpoint (JSON-RPC 2.0)"
      description: "Implements initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get for the `render_ascii` tool."
      responses:
        200:
          description: "JSON-RPC response"
          headers:
            traceparent:
              description: "W3C context for the A2V server span."
              schema:
                type: "string"
            X-PlatPhorm-Trace-Id:
              description: "Canonical 32-character trace identifier."
              schema:
                type: "string"
            X-PlatPhorm-Trace-Url:
              description: "Trace debugger URL for this operation."
              schema:
                type: "string"
                format: "uri"
            X-PlatPhorm-Trace-Export:
              description: "Trace export state: connected, degraded, or disabled."
              schema:
                type: "string"