{
  "openapi": "3.1.0",
  "info": {
    "title": "Opticosts Public API",
    "version": "1.0.0",
    "description": "B2B2C REST API for categorizing transactions, CO₂ estimates, and peer cohort comparison. Stateless: analyze does not store data. Authenticate with a Bearer API key issued in Admin → API keys."
  },
  "servers": [
    { "url": "/api/v1", "description": "Version 1" }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "API key from /admin/api-keys (prefix ocs_)"
      }
    },
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "required": ["transactions", "profile"],
        "properties": {
          "transactions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "type": "object",
              "required": ["date", "amountEur", "description"],
              "properties": {
                "date": { "type": "string", "example": "2026-07-15" },
                "amountEur": { "type": "number", "example": 42.5 },
                "description": { "type": "string", "example": "Albert Heijn Delft" }
              }
            }
          },
          "profile": {
            "type": "object",
            "required": ["ageBand", "profession", "region"],
            "properties": {
              "ageBand": { "type": "string", "example": "25-34" },
              "profession": { "type": "string", "example": "IT_TECH" },
              "region": { "type": "string", "example": "Zuid-Holland" }
            }
          }
        }
      }
    }
  },
  "security": [{ "ApiKeyBearer": [] }],
  "paths": {
    "/analyze": {
      "post": {
        "summary": "Analyze transactions",
        "description": "Categorize transactions, estimate CO₂, and compare category totals to peer cohorts. Nothing is stored.",
        "operationId": "analyze",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AnalyzeRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Categorized transactions + cohort comparison" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit (60 req/min)" }
        }
      }
    },
    "/categories": {
      "get": {
        "summary": "List categories",
        "description": "Category list with EEIO CO₂ factors (grams per euro).",
        "operationId": "listCategories",
        "responses": {
          "200": { "description": "Category list" },
          "401": { "description": "Missing or invalid API key" }
        }
      }
    },
    "/partners": {
      "get": {
        "summary": "List active partners",
        "description": "Public partner fields only. Filter by region and/or category slug.",
        "operationId": "listPartners",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "schema": { "type": "string" },
            "example": "Zuid-Holland"
          },
          {
            "name": "category",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Category slug",
            "example": "energy"
          }
        ],
        "responses": {
          "200": { "description": "Active partners" },
          "401": { "description": "Missing or invalid API key" }
        }
      }
    }
  }
}