{
  "name": "RUTHVEN Asset Intelligence API",
  "schema": "ruthven.asset/1",
  "read_only": true,
  "commercial": false,
  "principle": "claim → evidence → verification state. Nothing is returned as prose alone.",
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}",
      "returns": "the universal asset record"
    },
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}/evidence",
      "returns": "evidence records",
      "query": [
        "status",
        "type",
        "kind",
        "q"
      ]
    },
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}/evidence/{evidence_id}",
      "returns": "one evidence record"
    },
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}/provenance",
      "returns": "provenance, lineage, chain, tokenization, evidence graph"
    },
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}/verify?evidence={ids}",
      "returns": "state, hash and location of each record, to check independently"
    },
    {
      "method": "GET",
      "path": "/api/ruthven/assets/{asset_id}/proof?evidence={ids}&path={paths}",
      "returns": "a Merkle proof that each record is part of the issued Passport, with the steps to check it; with no ids, the paths that can be proved"
    },
    {
      "method": "POST",
      "path": "/api/ruthven/assets/{asset_id}/ask",
      "body": {
        "question": "string",
        "mode": "agent | human"
      },
      "returns": "claims with evidence ids and states"
    },
    {
      "method": "POST",
      "path": "/api/ruthven/mcp",
      "returns": "the same, as a Model Context Protocol server (when enabled)"
    },
    {
      "method": "POST",
      "path": "/api/ruthven/tools/origin-passport",
      "body": {
        "contract": "0x…",
        "token_id": "string",
        "asset_id": "string"
      },
      "returns": "the Origin Passport of one asset in brief, addressed by contract and token id or by asset id (when enabled; ERC-8257 manifest at /.well-known/ai-tool/origin-passport.json)"
    },
    {
      "method": "POST",
      "path": "/api/ruthven/tools/prove-claim",
      "body": {
        "asset_id": "string",
        "evidence_ids": [
          "EVID-…"
        ]
      },
      "returns": "the proof that a claim is part of that Passport (when enabled; manifest at /.well-known/ai-tool/prove-claim.json)"
    }
  ],
  "asset_id_forms": [
    "PT-0001",
    "RUTHVEN-PT-0000001",
    "1"
  ],
  "verification_states": [
    "VERIFIED",
    "CONTEXT",
    "INFERRED",
    "UNKNOWN"
  ],
  "public_states": [
    "VERIFIED",
    "CONTEXT",
    "NOT VERIFIED"
  ],
  "tokenization_statuses": [
    "NOT_TOKENIZED",
    "PLANNED",
    "TOKENIZED",
    "UNKNOWN"
  ],
  "permissions": [
    {
      "permission": "READ",
      "grant": "enabled",
      "meaning": "Retrieve the asset record, its evidence and its provenance.",
      "note": "Public records only; withheld claims stay withheld."
    },
    {
      "permission": "ANALYSE",
      "grant": "enabled",
      "meaning": "Ask questions answered from the evidence, with claims tied to evidence ids.",
      "note": "Never a valuation; never a claim without a state."
    },
    {
      "permission": "MONITOR",
      "grant": "disabled",
      "meaning": "Subscribe to changes in an asset or its evidence.",
      "note": "Not built. Freshness fields exist so it can be."
    },
    {
      "permission": "RECOMMEND",
      "grant": "limited",
      "meaning": "Suggest what to look at next.",
      "note": "Limited to follow-up questions about the record. No action, purchase, sale or financial recommendation."
    },
    {
      "permission": "PREPARE_ACTION",
      "grant": "disabled",
      "meaning": "Draft an action for a person to review.",
      "note": "Not built."
    },
    {
      "permission": "REQUEST_APPROVAL",
      "grant": "disabled",
      "meaning": "Ask an accountable person to approve a prepared action.",
      "note": "Not built."
    },
    {
      "permission": "EXECUTE",
      "grant": "disabled",
      "meaning": "Carry out an approved action.",
      "note": "Not built. RUTHVEN holds no keys and executes nothing."
    }
  ],
  "asset_types": [
    {
      "type": "digital_art",
      "status": "live",
      "label": "Digital artwork",
      "evidence_mutability": "immutable",
      "expected_fields": [
        "sourceWorks",
        "components",
        "constructionSequence",
        "hashes",
        "documents",
        "tokenization"
      ],
      "note": "First implementation: PAPER TRAIL. Evidence is content-addressed; a changed work is a new package version under a new CID, never an edit."
    },
    {
      "type": "real_property",
      "status": "placeholder",
      "label": "Real property",
      "evidence_mutability": "mutable",
      "expected_fields": [
        "title_number",
        "registered_owner",
        "consideration",
        "securities",
        "burdens",
        "planning",
        "site",
        "constraints",
        "development_signals",
        "documents",
        "evidence"
      ],
      "note": "PLACEHOLDER. Next asset class after PAPER TRAIL launches. No Registers of Scotland connection, no property UI, no opportunity scoring, no paid reports. A register changes: every evidence record will need retrieved_at, verified_at and source_updated_at to mean something, which is why they exist now."
    },
    {
      "type": "physical_art",
      "status": "reserved",
      "label": "Physical artwork",
      "evidence_mutability": "mutable",
      "expected_fields": [
        "dimensions",
        "medium",
        "condition",
        "custody",
        "exhibition_history",
        "documents"
      ],
      "note": "Reserved name."
    },
    {
      "type": "company",
      "status": "reserved",
      "label": "Company",
      "evidence_mutability": "mutable",
      "expected_fields": [
        "company_number",
        "jurisdiction",
        "officers",
        "share_capital",
        "filings",
        "charges"
      ],
      "note": "Reserved name."
    },
    {
      "type": "intellectual_property",
      "status": "reserved",
      "label": "Intellectual property",
      "evidence_mutability": "mutable",
      "expected_fields": [
        "right_type",
        "registration_number",
        "jurisdiction",
        "owner",
        "licences",
        "expiry"
      ],
      "note": "Reserved name."
    },
    {
      "type": "financial_instrument",
      "status": "reserved",
      "label": "Financial instrument",
      "evidence_mutability": "mutable",
      "expected_fields": [
        "instrument_type",
        "issuer",
        "terms",
        "underlying",
        "registrar"
      ],
      "note": "Reserved name. RUTHVEN describes; it does not price, trade or advise."
    },
    {
      "type": "other",
      "status": "reserved",
      "label": "Other asset",
      "evidence_mutability": "mutable",
      "expected_fields": [],
      "note": "A Passport type with no mapping yet lands here rather than being forced into a class it is not."
    }
  ]
}