{
  "openapi": "3.1.0",
  "info": {
    "title": "minitok public discovery and health API",
    "version": "discovery-metrics-v1",
    "description": "Public contract for health/readiness, anonymous allowlisted discovery intake, and the authorized aggregate discovery view. Remote MCP JSON-RPC is documented separately.",
    "license": { "name": "Private — minitok commercial software" }
  },
  "servers": [{ "url": "https://api.minitok.dev", "description": "Production API" }],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": ["health"],
        "responses": {
          "200": { "description": "Service is alive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }
        }
      }
    },
    "/readyz": {
      "get": {
        "operationId": "getReadiness",
        "tags": ["health"],
        "responses": {
          "200": { "description": "Readiness is healthy or not configured for this local process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } },
          "503": { "description": "Database readiness failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableResponse" } } } }
        }
      }
    },
    "/v1/discovery/events": {
      "post": {
        "operationId": "recordDiscoveryEvent",
        "tags": ["discovery"],
        "summary": "Record one allowlisted anonymous discovery event",
        "description": "Stores only a date/event/surface aggregate counter. Never send prompts, source code, tokens, identifiers, IP addresses, user-agents, cookies, sessions, referrers, or query data.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryEventInput" } } } },
        "responses": {
          "204": { "description": "Event accepted without a response body" },
          "400": { "description": "Payload is not allowlisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Public rate limit exceeded" }
        }
      }
    },
    "/v1/admin/discovery-events": {
      "get": {
        "operationId": "listDiscoveryEventAggregates",
        "tags": ["admin"],
        "summary": "List aggregate discovery counters for an authorized administrator",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }
        ],
        "responses": {
          "200": { "description": "Aggregate-only discovery rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryEventAggregateResponse" } } } },
          "400": { "description": "Invalid date range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Authentication required" },
          "403": { "description": "Administrator lacks permission" },
          "429": { "description": "Administrator rate limit exceeded" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Existing administrator authentication; never place a token in this public document." }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object", "additionalProperties": false, "required": ["status", "version"],
        "properties": { "status": { "const": "ok" }, "version": { "type": "string" } }
      },
      "ReadinessResponse": {
        "type": "object", "additionalProperties": false, "required": ["status", "db"],
        "properties": { "status": { "const": "ok" }, "db": { "type": "string", "enum": ["ok", "not-configured"] } }
      },
      "UnavailableResponse": {
        "type": "object", "additionalProperties": false, "required": ["status", "db"],
        "properties": { "status": { "const": "unavailable" }, "db": { "const": "error" } }
      },
      "ErrorResponse": {
        "type": "object", "additionalProperties": false, "required": ["error"],
        "properties": { "error": { "type": "string" } }
      },
      "DiscoveryEventInput": {
        "type": "object", "additionalProperties": false, "required": ["event", "surface"],
        "properties": {
          "event": { "type": "string", "enum": ["page_view", "demo_view", "install_copy", "guide_click", "official_link_click"] },
          "surface": { "type": "string", "enum": ["home", "docs", "demo", "pricing", "support", "verify-ai-generated-changes", "approve-and-recover-repository-changes", "record-ai-coding-evidence", "npm", "github", "privacy", "other"] }
        }
      },
      "DiscoveryEventAggregate": {
        "type": "object", "additionalProperties": false, "required": ["date_bucket", "event_name", "surface", "count"],
        "properties": {
          "date_bucket": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
          "event_name": { "type": "string", "enum": ["page_view", "demo_view", "install_copy", "guide_click", "official_link_click"] },
          "surface": { "type": "string" },
          "count": { "type": "integer", "minimum": 0 }
        }
      },
      "DiscoveryEventAggregateResponse": {
        "type": "object", "additionalProperties": false, "required": ["discovery_events"],
        "properties": { "discovery_events": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveryEventAggregate" } } }
      }
    }
  }
}