{
  "openapi": "3.1.0",
  "info": {
    "title": "Invoice Table Public API",
    "version": "0.4.3",
    "description": "Public endpoints for the Invoice Table browser workspace, subscriptions, support, and hosted MCP tools. Invoice contents selected in the browser workspace stay on the user's device. Hosted MCP tools receive only text or structured records explicitly supplied in each request."
  },
  "servers": [{ "url": "https://invoicetable.app", "description": "Production" }],
  "paths": {
    "/api/checkout-links": {
      "get": {
        "operationId": "getCheckoutLinks",
        "summary": "Get current Stripe checkout and billing-portal links",
        "responses": {
          "200": { "description": "Configured public Stripe links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLinks" } } } },
          "500": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/entitlement": {
      "get": {
        "operationId": "getEntitlement",
        "summary": "Read the active browser entitlement",
        "description": "Returns the free allowance or the paid subscription allowance associated with the secure browser cookie.",
        "responses": {
          "200": { "description": "Current entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } },
          "500": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/checkout/activate": {
      "get": {
        "operationId": "activateCheckout",
        "summary": "Activate a completed Stripe Checkout session in this browser",
        "parameters": [{ "name": "session_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 5 } }],
        "responses": {
          "200": { "description": "Paid entitlement activated", "headers": { "Set-Cookie": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } },
          "400": { "$ref": "#/components/responses/ApiError" },
          "404": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/usage": {
      "post": {
        "operationId": "recordDocumentUsage",
        "summary": "Record completed document usage for a paid entitlement",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["documents"], "properties": { "documents": { "type": "integer", "minimum": 1, "maximum": 25 } }, "additionalProperties": false } } } },
        "responses": {
          "200": { "description": "Updated entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } },
          "400": { "$ref": "#/components/responses/ApiError" },
          "403": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/support": {
      "post": {
        "operationId": "submitSupportRequest",
        "summary": "Submit an Invoice Table support request",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportRequest" } } } },
        "responses": {
          "201": { "description": "Support request accepted", "content": { "application/json": { "schema": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean", "const": true } } } } } },
          "400": { "$ref": "#/components/responses/ApiError" },
          "403": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "callInvoiceTableMcp",
        "summary": "Call the hosted Invoice Table MCP server",
        "description": "JSON-RPC endpoint implementing MCP server/discover, tools/list, and tools/call for three read-only invoice tools.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } },
        "responses": {
          "200": { "description": "JSON-RPC result or protocol error", "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc"], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": {}, "result": { "type": "object" }, "error": { "type": "object" } } } } } },
          "405": { "$ref": "#/components/responses/ApiError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CheckoutLinks": { "type": "object", "required": ["solo", "practice", "portal"], "properties": { "solo": { "type": ["string", "null"], "format": "uri" }, "practice": { "type": ["string", "null"], "format": "uri" }, "catchup": { "type": ["string", "null"], "format": "uri" }, "portal": { "type": ["string", "null"], "format": "uri" } } },
      "Entitlement": { "type": "object", "required": ["plan", "limit", "used", "remaining"], "properties": { "plan": { "type": "string", "enum": ["free", "solo", "practice"] }, "limit": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "currentPeriodEnd": { "type": ["integer", "null"] } } },
      "SupportRequest": { "type": "object", "required": ["requestId", "startedAt", "name", "email", "topic", "message"], "properties": { "requestId": { "type": "string", "format": "uuid" }, "startedAt": { "type": "integer" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 160 }, "topic": { "type": "string", "enum": ["install", "processing", "export", "billing", "privacy", "other"] }, "message": { "type": "string", "minLength": 10, "maxLength": 1200 }, "website": { "type": "string", "description": "Spam-trap field; leave empty." } }, "additionalProperties": false },
      "JsonRpcRequest": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "object" } }, "additionalProperties": false },
      "ApiError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "resolution": { "type": "string" } } }
    },
    "responses": {
      "ApiError": { "description": "Request error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    }
  }
}