{
  "openapi": "3.1.0",
  "info": {
    "title": "Cover Raccoon API",
    "version": "1",
    "description": "DeFi cover (insurance) index and analyses. The public catalog and coverage-gap check are read-only and free. A separate bearer-protected endpoint supplies current Nexus Mutual policies for one wallet to trusted monitoring agents. The full written analysis and purchase flow remain website-only.",
    "contact": {
      "url": "https://coverraccoon.com"
    }
  },
  "servers": [{ "url": "https://coverraccoon.com" }],
  "paths": {
    "/api/agent/v1/knowledge": {
      "get": {
        "operationId": "agentPublicKnowledge",
        "summary": "Public Coverraccoon and Nexus Mutual knowledge.",
        "description": "Versioned, read-only public explanations already visible in the free website teaser. Contains source URLs, update dates and explicit access=public markers. It never includes paid analysis text, wallet data, internal configuration or secrets. No authentication; rate limited to 20 requests/minute per IP.",
        "parameters": [{ "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": ["de", "en"], "default": "en" } }],
        "responses": {
          "200": { "description": "{ apiVersion: agent-knowledge.v1, language, generatedAt, count, entries[] }" },
          "429": { "description": "Rate limited." }
        }
      }
    },
    "/api/agent/v1/wallets/{wallet}/covers": {
      "get": {
        "operationId": "agentWalletCovers",
        "summary": "Current Nexus Mutual covers held by one wallet. Private agent API.",
        "description": "Returns current CoverNFT ownership joined with policy start, expiry, grace period and renewal lineage. Requires Authorization: Bearer <COVER_AGENT_API_KEY>. This endpoint is not exposed through the public MCP package.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "wallet", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }],
        "responses": {
          "200": { "description": "Current wallet policies and ownership synchronization cursors." },
          "400": { "description": "Invalid wallet address." },
          "404": { "description": "Not found (also used for missing/invalid credentials)." },
          "503": { "description": "Cover registry unavailable." }
        }
      }
    },
    "/api/cover/v1/analyses": {
      "get": {
        "operationId": "coverAnalyses",
        "summary": "Catalog of DeFi cover analyses. Free.",
        "description": "Free catalog of all cover analyses: Raccoon Score + band, covered protocol, audience (retail = protects the buyer, team = protects the buyer's users), coverage-gap counts, red flags, cheapest annual premium, analysis date, plus a web link to the full written analysis on the website. Discovery for agents: the provider and product slugs used by the check endpoint come from here. Rate limited to 20 requests/minute per IP.",
        "responses": {
          "200": { "description": "{ apiVersion, count, disclaimer, analyses[] }" },
          "429": { "description": "Rate limited." }
        }
      }
    },
    "/api/cover/v1/analyses/{provider}/{product}/check": {
      "get": {
        "operationId": "coverCheck",
        "summary": "Decision check for one DeFi cover: coverage gap map + red flags. Free.",
        "description": "Answers 'does this cover actually pay for my risk?' with the clause-by-clause coverage gap map (covered/conditional/excluded, with notes) plus all red-flag texts. Carries a signed attestation (offline verifiable) even though it is free. No payment, no receipt, built for high-frequency agent use. The full written analysis and the purchase flow are on the website only (see the web field in the response). Response shape: /api/cover/v1/schema. Rate limited to 20 requests/minute per IP.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "nexus-mutual"
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "uniswap-v3"
          }
        ],
        "responses": {
          "200": { "description": "The signed coverage gap map + red flags." },
          "404": { "description": "Unknown cover analysis." },
          "429": { "description": "Rate limited." }
        }
      }
    },
    "/api/cover/v1/schema": {
      "get": {
        "operationId": "coverSchema",
        "summary": "Free response schema of the analyses catalog and the check endpoint.",
        "description": "Placeholder-filled structure of what the catalog and check return, so agents can inspect the shape without an extra call. Free, cacheable. Rate limited to 20 requests/minute per IP.",
        "responses": {
          "200": { "description": "Schema document with placeholder values." },
          "429": { "description": "Rate limited." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" }
    }
  },
  "x-quickstart": [
    "1. Discover: GET /api/cover/v1/analyses (free) for provider/product slugs, score, audience, cheapest premium, and each product's web link to the full analysis.",
    "2. Optional: GET /api/cover/v1/schema (free) to preview the exact response shape.",
    "3. Decide: GET /api/cover/v1/analyses/{provider}/{product}/check (free) answers 'does this cover pay for my risk' with the clause-by-clause coverage gap map plus red flags, no payment, no receipt, call it as often as you like.",
    "The full written analysis (category-score reasoning, claims history, capital adequacy, sources) and the cover purchase flow are on the website only, at coverraccoon.com/cover/{provider}/{product} (see each catalog entry's web field) - not part of this API."
  ],
  "x-mcp": {
    "available": true,
    "tools": ["cover_list", "cover_check"],
    "note": "These two tools ship in the dedicated coverraccoon-mcp npm package and call the same two free endpoints as this manifest."
  }
}