{
  "openapi": "3.1.0",
  "info": {
    "title": "meterproof API",
    "version": "1.0.0",
    "summary": "Account, checkout and config generation for meterproof.",
    "description": "meterproof checks that Stripe will bill the usage your app recorded. The reconciler itself is a command line tool that runs on your machine; this API starts a subscription, manages the account and generates a meterproof.yml. Agents never handle card details: POST /api/checkout returns a Stripe Checkout URL that a person opens and confirms. The same actions are available over MCP at POST /mcp (Streamable HTTP, JSON responses)."
  },
  "servers": [{ "url": "https://meterproof.vibefrontier.com" }],
  "paths": {
    "/api/checkout": {
      "post": {
        "operationId": "startCheckout",
        "summary": "Create a Stripe Checkout Session for the meterproof subscription",
        "description": "Returns the Checkout URL. A person must open it and confirm payment. Browser forms (application/x-www-form-urlencoded) get a 303 redirect to Stripe instead of JSON. Rate limited per network.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } },
            "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } }
          }
        },
        "responses": {
          "200": { "description": "Checkout URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } } },
          "303": { "description": "Form post: redirect to Stripe Checkout (or back to /#pricing with ?checkout_error=<code>)" },
          "400": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/checkout/session": {
      "get": {
        "operationId": "getCheckoutSession",
        "summary": "Look up a finished Checkout Session; reveals the account token once",
        "description": "Used by the welcome page. For a completed, paid meterproof session it creates or updates the account and, the first time only, returns a new account token. Afterwards it returns token_already_shown instead.",
        "parameters": [
          { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^cs_(test|live)_[A-Za-z0-9]+$" } }
        ],
        "responses": {
          "200": { "description": "Session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/stripe/webhook": {
      "post": {
        "operationId": "stripeWebhook",
        "summary": "Stripe webhook receiver (called by Stripe only)",
        "description": "Verifies the Stripe-Signature header. Events whose object metadata.product is not meterproof are acknowledged and ignored.",
        "parameters": [{ "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" } } } } } },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/account": {
      "get": {
        "operationId": "getAccount",
        "summary": "Subscription status for the token holder",
        "security": [{ "accountToken": [] }],
        "responses": {
          "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/billing-portal": {
      "post": {
        "operationId": "openBillingPortal",
        "summary": "Create a Stripe billing portal session",
        "description": "Returns a URL for the person to update their card or cancel. Returns to /account/ afterwards.",
        "security": [{ "accountToken": [] }],
        "responses": {
          "200": { "description": "Portal URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tokens/rotate": {
      "post": {
        "operationId": "rotateToken",
        "summary": "Issue a new account token and revoke the presented one",
        "description": "The new token is shown only in this response.",
        "security": [{ "accountToken": [] }],
        "responses": {
          "200": { "description": "New token", "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "$ref": "#/components/schemas/Token" } } } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tokens/revoke": {
      "post": {
        "operationId": "revokeToken",
        "summary": "Revoke the presented account token",
        "security": [{ "accountToken": [] }],
        "responses": {
          "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true } } } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/config-template": {
      "get": {
        "operationId": "getConfigTemplate",
        "summary": "Generate a meterproof.yml",
        "description": "Values are validated and written as quoted YAML strings. Column names must be plain identifiers (letters, digits, underscore). With mapping=column the template expects the ledger to carry the Stripe customer id in a column named stripe_customer_id.",
        "parameters": [
          { "name": "meter_id", "in": "query", "schema": { "type": "string", "pattern": "^mtr_[A-Za-z0-9_]+$", "default": "mtr_REPLACE_ME" } },
          { "name": "ledger", "in": "query", "schema": { "type": "string", "enum": ["csv", "postgres", "sqlite"], "default": "csv" } },
          { "name": "customer_column", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "default": "customer" } },
          { "name": "timestamp_column", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "default": "timestamp" } },
          { "name": "quantity_column", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "default": "quantity" } },
          { "name": "mapping", "in": "query", "schema": { "type": "string", "enum": ["csv", "column"], "default": "csv" } },
          { "name": "price_id", "in": "query", "schema": { "type": "string", "pattern": "^price_[A-Za-z0-9_]+$" } }
        ],
        "responses": {
          "200": { "description": "meterproof.yml", "content": { "text/yaml": { "schema": { "type": "string" } } } },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Model Context Protocol endpoint (Streamable HTTP, stateless JSON-RPC 2.0)",
        "description": "Tools: get_setup_guide, generate_config, start_checkout, get_account, open_billing_portal, rotate_token. The last three need Authorization: Bearer mp_... on this request. Notifications get 202 with no body. GET returns 405.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } },
          "202": { "description": "Notification accepted" },
          "400": { "description": "Parse error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "accountToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token (mp_ followed by 43 URL-safe characters), shown once on the welcome page after checkout."
      }
    },
    "schemas": {
      "Token": { "type": "string", "pattern": "^mp_[A-Za-z0-9_-]{43}$" },
      "CheckoutRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "source": { "type": "string", "enum": ["web", "agent"], "default": "web" }
        }
      },
      "UrlResponse": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } },
      "Account": {
        "type": "object",
        "required": ["email", "status", "current_period_end"],
        "properties": {
          "email": { "type": ["string", "null"] },
          "status": { "type": "string", "description": "A Stripe subscription status: active, trialing, past_due, canceled, unpaid, incomplete, incomplete_expired, paused." },
          "current_period_end": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "SessionResponse": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "description": "open, expired or payment_pending while the session is not paid; otherwise the subscription status." },
          "email": { "type": "string" },
          "token": { "$ref": "#/components/schemas/Token" },
          "token_already_shown": { "type": "boolean", "const": true }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": { "error": { "type": "string" }, "message": { "type": "string" } }
      }
    },
    "responses": {
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}
