{
  "openapi": "3.1.0",
  "info": {
    "title": "KaijuConverter File Conversion & Format Matrix API",
    "version": "1.1.0",
    "description": "Public format discovery and cloud file conversion REST API for KaijuConverter (https://kaijuconverter.com). Supports 201+ file formats, 45 Studio Tools, and deterministic multilingual web URLs across 12 languages (see https://kaijuconverter.com/llms.txt).",
    "contact": {
      "name": "KaijuConverter Engineering",
      "url": "https://kaijuconverter.com/api-docs",
      "email": "hello@kaijuconverter.com"
    },
    "termsOfService": "https://kaijuconverter.com/terms"
  },
  "servers": [
    {
      "url": "https://kaijuconverter.com",
      "description": "Production HTTPS Server"
    }
  ],
  "paths": {
    "/api/mcp": {
      "get": {
        "operationId": "getMcpServerDescriptor",
        "summary": "Official Model Context Protocol (MCP) Streamable HTTP Server descriptor",
        "responses": {
          "200": {
            "description": "MCP server capabilities, protocolVersions, and available tool names."
          }
        }
      },
      "post": {
        "operationId": "callMcpJsonRpc",
        "summary": "Official MCP Streamable HTTP JSON-RPC 2.0 endpoint (initialize, tools/list, tools/call)",
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 result for list_supported_formats, get_conversion_targets, find_studio_tool, convert_file_from_url, or convert_base64_file."
          }
        }
      }
    },
    "/api/mcp/upload": {
      "post": {
        "operationId": "uploadAndConvertSingleStep",
        "summary": "Stateless 1-step multipart file upload and synchronous conversion (free up to 25 MB; Bearer API key up to 2 GB)",
        "responses": {
          "200": {
            "description": "Completed conversion metadata including download_url, output_size_bytes, sha256, and expires_at."
          }
        }
      }
    },
    "/api/v1/formats": {
      "get": {
        "operationId": "listSupportedFormats",
        "summary": "List all public file formats supported by KaijuConverter (no auth required)",
        "responses": {
          "200": {
            "description": "JSON list of supported formats, MIME types, families, and extensions."
          }
        }
      }
    },
    "/api/v1/formats/{format}/targets": {
      "get": {
        "operationId": "listFormatConversionTargets",
        "summary": "List all verified target output extensions for a given source extension (no auth required)",
        "parameters": [
          {
            "name": "format",
            "in": "path",
            "required": true,
            "description": "Lowercase file extension without leading dot (e.g. pdf, heic, jpg, docx, mp4, epub).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available target extensions and direct conversion URLs."
          }
        }
      }
    },
    "/available-targets/{ext}": {
      "get": {
        "operationId": "getWorkbenchAvailableTargets",
        "summary": "Quick lookup of verified target formats for an extension (no auth required)",
        "parameters": [
          {
            "name": "ext",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of verified target extensions for the source extension."
          }
        }
      }
    },
    "/api/v1/upload": {
      "post": {
        "operationId": "uploadSourceFile",
        "summary": "Upload a source file for cloud conversion (Bearer API key required)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Returns upload_id, detected_format, and available_targets."
          }
        }
      }
    },
    "/api/v1/convert": {
      "post": {
        "operationId": "startConversionJob",
        "summary": "Convert an uploaded file to target_format (Bearer API key required)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Returns job_id and conversion status."
          }
        }
      }
    },
    "/api/v1/convert/{id}/status": {
      "get": {
        "operationId": "getConversionJobStatus",
        "summary": "Poll conversion job progress and retrieve signed download_url (Bearer API key required)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status, output file size, SHA-256 checksum, and download_url."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}