{
  "openapi": "3.0.3",
  "info": {
    "title": "MilDex Militaria REST & Forensics API",
    "version": "1.0.0",
    "contact": {
      "name": "MilDex API Support",
      "url": "https://mildex.app/api-portal/",
      "email": "support@mildex.app"
    },
    "license": {
      "name": "MilDex Partner & Collector API License",
      "url": "https://mildex.app/api-portal/#terms"
    },
    "description": "Programmatic access to the **MilDex Militaria** phaleristic reference catalog, PkZ & LDO maker registry, metric authenticity verification, cryptographic certificates (`MDX-CHK`), steganographic seal inspection (`MDXF`), and personal collector vault synchronization.\n\n## Base URL\nAll endpoints listed below are relative to:\n```\nhttps://api.mildex.app/api/v1\n```\n\n## Authentication\nThe MilDex API uses two strictly separated authentication mechanisms depending on the domain:\n\n1. **Partner API Key (`X-API-Key`)** — Used for catalog lookups, variant queries, forensic verification (`POST /forensics/verify-specs`), and steganographic verification (`POST /watermark/verify`).\n   ```http\n   X-API-Key: mdx_live_your_partner_key\n   ```\n   > **Important:** Do **not** pass your Partner API key inside the `Authorization` header (e.g. `Authorization: Bearer mdx_live_...`). Partner keys are validated exclusively via `X-API-Key`; placing them in `Authorization` triggers `401 Unauthorized`.\n\n2. **Collector Bearer Token (`Authorization`)** — Used for personal collector vault operations (`/vault/items`) scoped to a verified Collector ID (`M/26-XXXX`).\n   ```http\n   Authorization: Bearer YOUR_COLLECTOR_TOKEN\n   ```\n\n## Rate Limits, Quotas & Anti-Scraping\n- **Sliding-Window Rate Limit:** Default `60 requests / minute` per partner client.\n- **Monthly Quota:** Enforced against your configured partner plan (`requests_used_month` / `monthly_quota`).\n- **Anti-Scraping Protection:** Partner queries against `GET /forensics/variants` are capped at **25 variants per request**.\n\n## HTTP Status & Error Codes\n| Status | Meaning | Typical Cause |\n| :--- | :--- | :--- |\n| `401 Unauthorized` | Authentication failed | Missing or invalid `X-API-Key` header or expired Bearer token |\n| `403 Forbidden` | Client disabled / restricted | Partner key deactivated or watermark sealing disabled for tier |\n| `404 Not Found` | Resource missing | Unknown `award_id`, maker slug, or `verification_id` |\n| `413 Payload Too Large` | Image limit exceeded | Base64 image payload exceeds `15 MB` |\n| `422 Unprocessable Entity` | Validation error | Invalid field types or missing required fields |\n| `429 Too Many Requests` | Rate limit / quota exceeded | Burst above per-minute limit or monthly quota exhausted |\n\n## Language Negotiation\nPass `?lang=de` or `?lang=en` as a query parameter, or send a standard `Accept-Language` HTTP header (q-factor aware). Defaults to `de`."
  },
  "servers": [
    {
      "url": "https://api.mildex.app/api/v1",
      "description": "Production API Gateway"
    },
    {
      "url": "http://localhost:8000/api/v1",
      "description": "Local Development Server"
    }
  ],
  "tags": [
    {
      "name": "Catalog & Variants",
      "description": "Search and inspect documented orders, decorations, edged weapons, and specialist literature variants."
    },
    {
      "name": "Makers (PkZ & LDO)",
      "description": "Präsidialkanzlei (PkZ), Leistungsgemeinschaft Deutscher Ordenshersteller (LDO), and RZM maker master dossiers."
    },
    {
      "name": "Forensics & Verification",
      "description": "Metric tolerance checks, risk scoring, cryptographic certificates (`MDX-CHK`), and optional steganographic sealing."
    },
    {
      "name": "Steganography & Provenance (MDXF)",
      "description": "Verify invisible LSB `MDXF` provenance fingerprints embedded in sealed auction or catalog images."
    },
    {
      "name": "Collector Vault",
      "description": "Manage personal collection items tied to a verified MilDex Collector ID (`M/26-XXXX`)."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Phaleristic Catalog",
      "tags": ["Catalog & Variants", "Makers (PkZ & LDO)"]
    },
    {
      "name": "Authenticity & Forensics",
      "tags": ["Forensics & Verification", "Steganography & Provenance (MDXF)"]
    },
    {
      "name": "Collector Services",
      "tags": ["Collector Vault"]
    }
  ],
  "components": {
    "securitySchemes": {
      "PartnerApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "B2B Partner API Key issued by MilDex (`mdx_live_...`). Must be sent in `X-API-Key`."
      },
      "CollectorBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Verified Collector session token for personal vault endpoints."
      }
    },
    "parameters": {
      "LangQuery": {
        "name": "lang",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": ["de", "en"],
          "default": "de"
        },
        "description": "Optional explicit language override (`de` or `en`). Overrides `Accept-Language`."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "example": "Ungültiger MilDex B2B API-Key (X-API-Key)."
          }
        },
        "required": ["detail"]
      },
      "MakerSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 12 },
          "slug": { "type": "string", "example": "c-e-juncker-berlin" },
          "name": { "type": "string", "example": "C.E. Juncker, Berlin" },
          "name_de": { "type": "string", "nullable": true, "example": "C.E. Juncker, Berlin" },
          "name_en": { "type": "string", "nullable": true, "example": "C.E. Juncker, Berlin" },
          "location": { "type": "string", "nullable": true, "example": "Berlin" },
          "pkz_number": { "type": "string", "nullable": true, "example": "2" },
          "ldo_number": { "type": "string", "nullable": true, "example": "L/12" },
          "rzm_code": { "type": "string", "nullable": true, "example": "M1/105" },
          "short_codes": {
            "type": "array",
            "items": { "type": "string" },
            "nullable": true,
            "example": ["CEJ", "L/12", "PKZ 2"]
          },
          "maker_category": { "type": "string", "example": "known_maker" },
          "hallmark_image_url": { "type": "string", "nullable": true }
        }
      },
      "VariantSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 106 },
          "award_id": { "type": "integer", "example": 2 },
          "catalog_no": { "type": "string", "nullable": true, "example": "1.06.1" },
          "variant_name": { "type": "string", "nullable": true, "example": "C.E. Juncker (Hohlprägung Neusilber)" },
          "maker_name": { "type": "string", "nullable": true, "example": "C.E. Juncker, Berlin" },
          "maker_location": { "type": "string", "nullable": true, "example": "Berlin" },
          "material": { "type": "string", "nullable": true, "example": "Neusilber / Buntmetall" },
          "height_mm": { "type": "number", "format": "float", "nullable": true, "example": 61.55 },
          "width_mm": { "type": "number", "format": "float", "nullable": true, "example": 46.85 },
          "weight_g": { "type": "number", "format": "float", "nullable": true, "example": 26.0 },
          "hinge_type": { "type": "string", "nullable": true, "example": "Blockscharnier auf Sockel" },
          "catch_type": { "type": "string", "nullable": true, "example": "Flachdraht-C-Haken" },
          "is_catch_magnetic": { "type": "boolean", "nullable": true, "example": false },
          "maker_marks": {
            "type": "array",
            "items": { "type": "string" },
            "nullable": true,
            "example": ["CEJ", "L/12"]
          },
          "distinguishing_features": {
            "type": "array",
            "items": { "type": "string" },
            "nullable": true
          },
          "is_original": { "type": "boolean", "example": true },
          "image_url_front": { "type": "string", "nullable": true },
          "image_url_back": { "type": "string", "nullable": true },
          "image_url_mark": { "type": "string", "nullable": true }
        }
      },
      "AwardDetail": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 2 },
          "name": { "type": "string", "example": "Infanterie-Sturmabzeichen (ISA)" },
          "category": { "type": "string", "example": "Heer" },
          "institution_date": { "type": "string", "example": "20. Dezember 1939" },
          "description": { "type": "string" },
          "taxonomy_code": { "type": "string", "nullable": true, "example": "HEER-KAMPF-01" },
          "image_url_front": { "type": "string", "nullable": true },
          "image_url_back": { "type": "string", "nullable": true },
          "variants": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/VariantSummary" }
          }
        }
      },
      "MakerDossier": {
        "allOf": [
          { "$ref": "#/components/schemas/MakerSummary" },
          {
            "type": "object",
            "properties": {
              "description_de": { "type": "string", "nullable": true },
              "description_en": { "type": "string", "nullable": true },
              "variants_count": { "type": "integer", "example": 18 },
              "awards_count": { "type": "integer", "example": 9 },
              "variants": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/VariantSummary" }
              }
            }
          }
        ]
      },
      "MetricVerificationRequest": {
        "type": "object",
        "properties": {
          "award_id": {
            "type": "integer",
            "nullable": true,
            "description": "Award ID (e.g. 2 for Infanterie-Sturmabzeichen).",
            "example": 2
          },
          "award_name": {
            "type": "string",
            "nullable": true,
            "default": "Infanterie-Sturmabzeichen",
            "description": "Award name or search query if `award_id` is omitted.",
            "example": "Infanterie-Sturmabzeichen"
          },
          "catalog_no": {
            "type": "string",
            "nullable": true,
            "description": "Specialist literature catalog number (e.g. `1.06.1`).",
            "example": "1.06.1"
          },
          "maker_mark": {
            "type": "string",
            "nullable": true,
            "description": "Stamped or raised maker mark (e.g. `L/12`, `f.O.`, `M.K.1`).",
            "example": "L/12"
          },
          "measured_weight_g": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Measured specimen weight in grams.",
            "example": 26.0
          },
          "measured_height_mm": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Measured specimen height in millimeters.",
            "example": 61.55
          },
          "measured_width_mm": {
            "type": "number",
            "format": "float",
            "nullable": true,
            "description": "Measured specimen width in millimeters.",
            "example": 46.85
          },
          "catch_type": {
            "type": "string",
            "nullable": true,
            "description": "Observed catch hardware type."
          },
          "is_catch_magnetic": {
            "type": "boolean",
            "default": false,
            "description": "Whether the catch responds to a neodymium magnet."
          },
          "image_base64": {
            "type": "string",
            "nullable": true,
            "description": "Optional Base64 object photo (max 15 MB) for visible Curator Seal + invisible MDXF steganography."
          },
          "apply_verification_seal": {
            "type": "boolean",
            "default": false,
            "description": "Embeds visible seal + invisible MDXF fingerprint when verdict passes without critical alert."
          }
        }
      },
      "ToleranceAnalysis": {
        "type": "object",
        "properties": {
          "weight_target_g": { "type": "number", "nullable": true, "example": 26.0 },
          "weight_delta_g": { "type": "number", "nullable": true, "example": 0.0 },
          "weight_delta_percent": { "type": "number", "nullable": true, "example": 0.0 },
          "height_target_mm": { "type": "number", "nullable": true, "example": 61.55 },
          "height_delta_mm": { "type": "number", "nullable": true, "example": 0.0 },
          "width_target_mm": { "type": "number", "nullable": true, "example": 46.85 },
          "width_delta_mm": { "type": "number", "nullable": true, "example": 0.0 },
          "magnetic_catch_match": { "type": "boolean", "nullable": true, "example": true }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "properties": {
          "verification_id": { "type": "string", "example": "MDX-CHK-2026-493190" },
          "verification_url": {
            "type": "string",
            "example": "https://api.mildex.app/api/v1/forensics/certificates/MDX-CHK-2026-493190"
          },
          "client_id": { "type": "string", "example": "MDX-PARTNER-001" },
          "status": {
            "type": "string",
            "enum": ["VERIFIED_MATCH", "TOLERANCE_WARNING", "CRITICAL_ALERT", "NO_MATCH"],
            "example": "VERIFIED_MATCH"
          },
          "authenticity_rating": { "type": "string", "example": "ORIGINAL_TOLERANCE_VERIFIED" },
          "risk_score": { "type": "number", "format": "float", "example": 0.0 },
          "matched_variant": { "$ref": "#/components/schemas/VariantSummary" },
          "tolerance_analysis": { "$ref": "#/components/schemas/ToleranceAnalysis" },
          "critical_warnings": {
            "type": "array",
            "items": { "type": "string" },
            "example": []
          },
          "forensic_assessment": { "type": "string" },
          "distinguishing_checkpoints": {
            "type": "array",
            "items": { "type": "string" }
          },
          "sealed_image_data_url": {
            "type": "string",
            "nullable": true,
            "description": "Data URL of PNG with visible Curator Seal and invisible MDXF fingerprint."
          }
        }
      },
      "VaultItemPayload": {
        "type": "object",
        "required": ["collector_id", "award_id"],
        "properties": {
          "collector_id": { "type": "string", "example": "M/26-0001" },
          "award_id": { "type": "integer", "example": 2 },
          "variant_id": { "type": "integer", "nullable": true, "example": 106 },
          "maker_slug": { "type": "string", "nullable": true, "example": "c-e-juncker-berlin" },
          "catalog_no": { "type": "string", "nullable": true, "example": "1.06.1" },
          "variant_name": { "type": "string", "nullable": true, "example": "C.E. Juncker L/12" },
          "condition": { "type": "string", "default": "worn", "example": "mint" },
          "purchase_price_eur": { "type": "number", "nullable": true, "example": 480.0 },
          "notes": { "type": "string", "nullable": true, "example": "Verified die strike & block hinge." },
          "added_at": { "type": "string", "nullable": true, "example": "2026-11-15" }
        }
      },
      "VaultItem": {
        "allOf": [
          { "$ref": "#/components/schemas/VaultItemPayload" },
          {
            "type": "object",
            "properties": {
              "id": { "type": "integer", "example": 42 },
              "image_url": { "type": "string", "nullable": true },
              "updated_at": { "type": "string", "format": "date-time", "nullable": true }
            }
          }
        ]
      }
    }
  },
  "paths": {
    "/awards": {
      "get": {
        "tags": ["Catalog & Variants"],
        "summary": "List & search phaleristic awards",
        "description": "Returns curated orders, combat badges, campaign shields, and edged weapons with full-text search, category filtering, and cursor pagination. Sets `X-Total-Count` response header.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Full-text search term (e.g. `Infanterie-Sturmabzeichen`, `Juncker`)." },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category ID or localized category filter." },
          { "name": "cursor", "in": "query", "schema": { "type": "integer" }, "description": "Award ID cursor for O(1) pagination." },
          { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500 } },
          { "$ref": "#/components/parameters/LangQuery" }
        ],
        "responses": {
          "200": {
            "description": "Array of localized award records.",
            "headers": {
              "X-Total-Count": {
                "schema": { "type": "integer" },
                "description": "Total number of matching awards in catalog."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AwardDetail" }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl \"https://api.mildex.app/api/v1/awards?q=Infanterie&lang=de&limit=20\""
          },
          {
            "lang": "Python",
            "source": "import requests\n\nr = requests.get(\n    \"https://api.mildex.app/api/v1/awards\",\n    params={\"q\": \"Infanterie\", \"lang\": \"de\", \"limit\": 20},\n)\nprint(r.headers.get(\"X-Total-Count\"), len(r.json()))"
          },
          {
            "lang": "JavaScript",
            "source": "const res = await fetch(\"https://api.mildex.app/api/v1/awards?q=Infanterie&lang=en\");\nconst awards = await res.json();"
          }
        ]
      }
    },
    "/awards/{award_id}": {
      "get": {
        "tags": ["Catalog & Variants"],
        "summary": "Get full award dossier by ID",
        "description": "Fetches complete award metadata, historical conferring context, physical tolerances, counterfeit guide checkpoints, and all documented maker variants.",
        "parameters": [
          { "name": "award_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 2 },
          { "$ref": "#/components/parameters/LangQuery" }
        ],
        "responses": {
          "200": {
            "description": "Complete award dossier.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AwardDetail" }
              }
            }
          },
          "404": {
            "description": "Award not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl \"https://api.mildex.app/api/v1/awards/2?lang=en\""
          }
        ]
      }
    },
    "/forensics/variants": {
      "get": {
        "tags": ["Catalog & Variants"],
        "summary": "Partner variant lookup (anti-scraping limited)",
        "description": "Targeted lookup of documented maker variants by `award_id`, `award_name`, `catalog_no`, or `maker`. Limited to **max. 25 variants per request** for B2B Partner API keys.",
        "security": [{ "PartnerApiKey": [] }],
        "parameters": [
          { "name": "award_id", "in": "query", "schema": { "type": "integer" }, "example": 2 },
          { "name": "award_name", "in": "query", "schema": { "type": "string" } },
          { "name": "catalog_no", "in": "query", "schema": { "type": "string" }, "example": "1.06.1" },
          { "name": "maker", "in": "query", "schema": { "type": "string" }, "example": "Juncker" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 25 } }
        ],
        "responses": {
          "200": {
            "description": "Matching reference variants.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/VariantSummary" }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid `X-API-Key`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -H \"X-API-Key: mdx_live_your_key\" \\\n  \"https://api.mildex.app/api/v1/forensics/variants?award_id=2&maker=Juncker&limit=10\""
          }
        ]
      }
    },
    "/makers": {
      "get": {
        "tags": ["Makers (PkZ & LDO)"],
        "summary": "List all registered PkZ, LDO & RZM makers",
        "description": "Returns master metadata for all historical manufacturers including Präsidialkanzlei numbers (`pkz_number`), LDO codes (`ldo_number`), RZM codes, short hallmark codes, and hallmark images.",
        "responses": {
          "200": {
            "description": "List of makers ordered alphabetically.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/MakerSummary" }
                }
              }
            }
          }
        }
      }
    },
    "/makers/{id_or_slug}": {
      "get": {
        "tags": ["Makers (PkZ & LDO)"],
        "summary": "Get complete maker dossier & variants",
        "description": "Resolves a maker by numeric ID or canonical slug (e.g. `c-e-juncker-berlin`) and returns historical notes alongside all published variants across awards.",
        "parameters": [
          {
            "name": "id_or_slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "c-e-juncker-berlin"
          }
        ],
        "responses": {
          "200": {
            "description": "Complete maker dossier.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MakerDossier" }
              }
            }
          },
          "404": {
            "description": "Maker not found.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/forensics/verify-specs": {
      "post": {
        "tags": ["Forensics & Verification"],
        "summary": "Verify metric specs & optionally apply MDXF seal",
        "description": "Compares measured weight (`g`), height (`mm`), width (`mm`), catch magnetism, and maker marks against verified reference variants. Issues a persistent `MDX-CHK` certificate URL and, when `apply_verification_seal: true` and no `CRITICAL_ALERT` occurs, embeds both a visible Curator Seal and an invisible `MDXF` LSB steganographic fingerprint.",
        "security": [{ "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MetricVerificationRequest" },
              "example": {
                "award_name": "Infanterie-Sturmabzeichen",
                "catalog_no": "1.06.1",
                "measured_height_mm": 61.55,
                "measured_width_mm": 46.85,
                "measured_weight_g": 26.0,
                "is_catch_magnetic": false,
                "apply_verification_seal": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Forensic tolerance verdict & public certificate link.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerificationResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid `X-API-Key`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "404": {
            "description": "Award or matching reference variant not found.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X POST https://api.mildex.app/api/v1/forensics/verify-specs \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: mdx_live_your_key\" \\\n  -d '{\n    \"catalog_no\": \"1.06.1\",\n    \"measured_height_mm\": 61.55,\n    \"measured_width_mm\": 46.85,\n    \"measured_weight_g\": 26.0,\n    \"is_catch_magnetic\": false\n  }'"
          },
          {
            "lang": "Python",
            "source": "import requests\n\nres = requests.post(\n    \"https://api.mildex.app/api/v1/forensics/verify-specs\",\n    headers={\"X-API-Key\": \"mdx_live_your_key\"},\n    json={\n        \"catalog_no\": \"1.06.1\",\n        \"measured_height_mm\": 61.55,\n        \"measured_width_mm\": 46.85,\n        \"measured_weight_g\": 26.0,\n        \"is_catch_magnetic\": False,\n    },\n)\nprint(res.json()[\"verification_id\"], res.json()[\"status\"])"
          }
        ]
      }
    },
    "/forensics/certificates/{verification_id}": {
      "get": {
        "tags": ["Forensics & Verification"],
        "summary": "Public verification certificate lookup",
        "description": "Allows buyers, auction bidders, and collectors to independently verify an `MDX-CHK-2026-XXXXXX` forensic certificate ID.",
        "parameters": [
          {
            "name": "verification_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "MDX-CHK-2026-493190"
          }
        ],
        "responses": {
          "200": {
            "description": "Stored forensic certificate summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification_id": { "type": "string", "example": "MDX-CHK-2026-493190" },
                    "verified_by": { "type": "string", "example": "MilDex Phaleristic Forensics Engine" },
                    "partner_name": { "type": "string", "example": "Authorized Auction Partner" },
                    "catalog_no": { "type": "string", "example": "1.06.1" },
                    "maker_name": { "type": "string", "example": "C.E. Juncker, Berlin" },
                    "status": { "type": "string", "example": "VERIFIED_MATCH" },
                    "authenticity_rating": { "type": "string" },
                    "risk_score": { "type": "number", "example": 0.0 },
                    "steganographic_seal_issued": { "type": "boolean", "example": true },
                    "issued_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Verification certificate not found.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/watermark/verify": {
      "post": {
        "tags": ["Steganography & Provenance (MDXF)"],
        "summary": "Extract & verify invisible MDXF fingerprint",
        "description": "Reads invisible LSB steganography (`MDXF` payload) embedded in sealed MilDex reference or partner exhibit photographs to verify provenance (`client_id`, `license_id`, `item_id`).",
        "security": [{ "PartnerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": { "type": "string", "nullable": true },
                  "image_base64": { "type": "string", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Steganographic inspection result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": { "type": "boolean", "example": true },
                    "status": { "type": "string", "enum": ["VALID_FINGERPRINT", "NO_FINGERPRINT"] },
                    "message": { "type": "string" },
                    "data": { "type": "object", "nullable": true }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "413": {
            "description": "Image exceeds 15 MB.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/vault/items": {
      "get": {
        "tags": ["Collector Vault"],
        "summary": "List personal collector vault items",
        "description": "Returns all private collection entries stored for the authenticated Collector ID (`M/26-XXXX`).",
        "security": [{ "CollectorBearer": [] }],
        "parameters": [
          {
            "name": "collector_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "M/26-0001"
          }
        ],
        "responses": {
          "200": {
            "description": "Collector vault entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/VaultItem" }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Collector Bearer token.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      },
      "put": {
        "tags": ["Collector Vault"],
        "summary": "Create or update a collector vault item",
        "description": "Upserts a collection piece by `(collector_id, variant_id)` or `(collector_id, award_id)` while preserving catalog metadata.",
        "security": [{ "CollectorBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VaultItemPayload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved vault entry.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VaultItem" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Collector Bearer token.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    }
  }
}
