{
  "contract": "apis-vin/icp",
  "version": 1,
  "description": "Agent self-classification for the estate API. Read your class to know which flow fits; every class listed works today against the sandbox, and nothing listed is planned-only.",
  "agent_classes": [
    {
      "id": "anonymous-reader",
      "fit": "You read VIN records with no key and no account.",
      "flow": "GET /decode/{vin}, GET /listings, GET /{VIN} (the record face) — typed OK / EMPTY / BLOCKED envelopes on every door; the quartet at the root describes the rest."
    },
    {
      "id": "anonymous-registrant",
      "fit": "You want an account context without a human in the loop.",
      "flow": "POST /keys — no email, no approval, no CAPTCHA — answers vk_sandbox_… exactly once (stored only as a sha256 hash); introspect it at GET /keys/me."
    },
    {
      "id": "sandbox-transactor",
      "fit": "You drive the transaction verbs — deals, F&I, credit — against the deterministic sandbox.",
      "flow": "POST /buy/deals, POST /fi/quotes, POST /credit/prequal and the rest of the lifecycle. Keyless surfaces stay keyless; Bearer vk_sandbox_… adds account context. Every simulated payload carries {\"environment\":\"sandbox\",\"simulated\":true}."
    },
    {
      "id": "dealer-operator",
      "fit": "You work the dealer side — inventory, leads, and the deal-side book.",
      "flow": "GET /dealer/inventory (the platform listings projected for a dealer — answers keyless), POST /dealer/leads (lead capture), GET /dealer/deals and /dealer/deals/{dealId} (the deal-side book). The lead and book doors require Bearer vk_sandbox_… — the account is the dealer identity."
    }
  ],
  "ladder": [
    {
      "rung": "anonymous",
      "auth": "none",
      "grants": "every keyless read surface answers in full — the quartet, /listings, /decode/{vin}, the record face — and POST /keys mints a sandbox key with no email, no approval, no CAPTCHA"
    },
    {
      "rung": "sandbox-key",
      "auth": "Authorization: Bearer vk_sandbox_…",
      "obtain": "POST /keys — fully self-service; the key is returned exactly once and stored only as a sha256 hash",
      "grants": "account context (GET /keys/me) on top of every keyless surface; it never unlocks licensed or premium data tiers — the money gate is mandates and settlement, not registration"
    }
  ],
  "not_for": [
    "licensed or premium data tiers (book values, sticker, vehicle history) — not served at any rung here",
    "production money movement — the sandbox settles simulated funds only"
  ]
}