{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenTex Platform & Agent API",
    "version": "1.0.0",
    "description": "API schema for OpenTex: in-browser and server-backed LaTeX compilation, document conversion, citation resolution, and AI agent coordination.",
    "contact": {
      "name": "OpenTex Support",
      "url": "https://opentex.yashvardhan.dev",
      "email": "vs21yash@gmail.com"
    }
  },
  "servers": [
    {
      "url": "https://opentex.yashvardhan.dev/api",
      "description": "Production Edge API Gateway"
    }
  ],
  "paths": {
    "/compile": {
      "post": {
        "summary": "Compile LaTeX project to PDF",
        "description": "Compiles a bundle of LaTeX source files and assets into a PDF document using the server compile lane with diagnostic logs.",
        "operationId": "compileLatex",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entryFile", "files"],
                "properties": {
                  "entryFile": {
                    "type": "string",
                    "example": "main.tex"
                  },
                  "engine": {
                    "type": "string",
                    "enum": ["pdflatex", "xelatex", "lualatex"],
                    "default": "pdflatex"
                  },
                  "files": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "object",
                      "properties": {
                        "text": { "type": "string" },
                        "b64": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compilation successful or finished with log",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "pdfBase64": { "type": "string" },
                    "log": { "type": "string" },
                    "compiler": { "type": "string" },
                    "diagnostics": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "file": { "type": "string" },
                          "line": { "type": "integer" },
                          "severity": { "type": "string" },
                          "message": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/convert": {
      "post": {
        "summary": "Convert scientific image to LaTeX via VLM",
        "description": "Converts images containing mathematical formulas, tables, or scientific diagrams into compilable LaTeX source code using a vision-language model. Supports multipart/form-data file uploads or application/json with base64 imageData.",
        "operationId": "convertImageToLatex",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Image file (PNG, JPEG, WEBP) up to 10MB (max 8 files)"
                  },
                  "modelId": {
                    "type": "string",
                    "description": "Optional model identifier override (e.g. gemini-2.5-flash)"
                  },
                  "apiKey": {
                    "type": "string",
                    "description": "Optional provider API key for BYOK usage"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["imageData"],
                "properties": {
                  "imageData": {
                    "type": "string",
                    "description": "Base64-encoded image data"
                  },
                  "mimeType": {
                    "type": "string",
                    "default": "image/png"
                  },
                  "modelId": {
                    "type": "string"
                  },
                  "apiKey": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Converted LaTeX results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "filename": { "type": "string" },
                          "latex": { "type": "string" },
                          "modelId": { "type": "string" },
                          "cached": { "type": "boolean" },
                          "confidence": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing image file or invalid model ID"
          },
          "413": {
            "description": "Image payload exceeds size or file count limits"
          },
          "429": {
            "description": "Rate limit or daily conversion quota exceeded"
          }
        }
      }
    },
    "/cite": {
      "post": {
        "summary": "Resolve academic citation",
        "description": "Resolves citation queries (prefixed with 'arxiv:' for arXiv papers, DOIs containing '10.', or title query strings) into verified BibTeX citations.",
        "operationId": "resolveCitation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Citation query identifier: 'arxiv:<id>' (e.g. 'arxiv:2303.08774'), DOI ('10.1145/...'), or paper title.",
                    "example": "arxiv:2303.08774"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved BibTeX citation record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bibtex": { "type": "string" },
                    "key": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Query missing or invalid"
          },
          "422": {
            "description": "Citation could not be resolved from upstream sources"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/agent/capabilities": {
      "get": {
        "summary": "Inspect Agent & Edge AI Capabilities",
        "description": "Returns status of Edge AI availability, model identity, and BYOK support.",
        "operationId": "getAgentCapabilities",
        "responses": {
          "200": {
            "description": "Agent capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "edgeAvailable": { "type": "boolean" },
                    "byokAvailable": { "type": "boolean" },
                    "modelId": { "type": "string" },
                    "modelLabel": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
