{
  "openapi": "3.1.0",
  "info": {
    "title": "QBO Maker Convert API",
    "version": "1.0.0",
    "description": "Convert bank transaction data into QuickBooks-ready .QBO (Web Connect), Quicken .QFX, generic .OFX, or a QuickBooks 3-column .CSV, and validate existing files. The /convert endpoint requires a Pro API key; /validate is public.",
    "contact": { "name": "QBO Maker", "url": "https://qbomaker.com" }
  },
  "servers": [{ "url": "https://api.qbomaker.com", "description": "Hosted Convert API (Cloudflare Worker)" }],
  "paths": {
    "/convert": {
      "post": {
        "summary": "Convert transactions to QBO/QFX/OFX/CSV",
        "operationId": "convert",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertRequest" },
            "example": { "format": "qbo", "accountType": "CHECKING", "bankId": "021000021", "transactions": [
              { "date": "01/05/2024", "amount": -42.5, "description": "Coffee Shop" },
              { "date": "01/06/2024", "amount": 2000, "description": "Payroll" }
            ] } } }
        },
        "responses": {
          "200": { "description": "Conversion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" } } } },
          "400": { "description": "Bad request (invalid format/accountType, empty or non-object transactions)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "format must be one of qbo, qfx, ofx, csv." } } } },
          "401": { "description": "Missing or invalid Pro API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid or missing API key." } } } },
          "413": { "description": "Too many transactions (max 100000)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Too many transactions (max 100000)." } } } }
        }
      }
    },
    "/validate": {
      "post": {
        "summary": "Validate an OFX/QBO/QFX document",
        "operationId": "validate",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } } }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP JSON-RPC endpoint (initialize, tools/list, tools/call)",
        "operationId": "mcp",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "JSON-RPC response" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Pro API key, e.g. Authorization: Bearer QBOM-PRO-..." } },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } },
      "Transaction": {
        "type": "object", "required": ["date", "amount", "description"],
        "properties": {
          "date": { "type": "string", "description": "Any common date format" },
          "amount": { "type": "number", "description": "Signed: negative=debit, positive=credit" },
          "description": { "type": "string" },
          "memo": { "type": "string" },
          "checkNumber": { "type": "string" }
        }
      },
      "ConvertRequest": {
        "type": "object", "required": ["transactions"],
        "properties": {
          "format": { "type": "string", "enum": ["qbo", "qfx", "ofx", "csv"], "default": "qbo" },
          "currency": { "type": "string", "description": "3-letter code, e.g. USD, GBP, EUR", "default": "USD" },
          "accountType": { "type": "string", "enum": ["CHECKING", "SAVINGS", "CREDITCARD", "MONEYMRKT"], "default": "CHECKING" },
          "bankId": { "type": "string" },
          "accountId": { "type": "string" },
          "responseType": { "type": "string", "enum": ["json", "file"], "default": "json" },
          "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }
        }
      },
      "ConvertResponse": {
        "type": "object",
        "properties": {
          "format": { "type": "string" },
          "transactions": { "type": "integer", "description": "Count of transactions emitted (rows kept)." },
          "skipped": { "type": "integer", "description": "Rows dropped for an unreadable date or amount." },
          "inputCount": { "type": "integer", "description": "Total transactions supplied in the request." },
          "valid": { "type": "boolean", "description": "For format=csv this is always true (the OFX validator does not apply)." },
          "issues": { "type": "array", "items": { "type": "string" } },
          "file": { "type": "string", "description": "The OFX/QBO/QFX/CSV document" }
        }
      },
      "ValidateResponse": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "issues": { "type": "array", "items": { "type": "string" } },
          "stats": { "type": "object", "properties": { "transactions": { "type": "integer" }, "uniqueFitids": { "type": "integer" }, "hasIntuBid": { "type": "boolean" } } }
        }
      }
    }
  }
}