Media reliability

Media endpoints report whether an asset's canonical image URI is reachable, attempt recovery when it is not, and optionally preserve bytes in Cloudflare R2.

Base URL: https://api.owlviz.dev

Media reliability is **separate from metadata health**. A recovered display URL does not remove IMAGE_MISSING or off-chain failures on the canonical metadata path.

Endpoints

Query / body

Response shape

{
  "data": {
    "assetId": "<mint>",
    "image": {
      "canonicalUri": "https://...",
      "bestAvailableUri": "https://...",
      "status": "healthy",
      "origin": {
        "provider": "https",
        "uri": "https://...",
        "reachable": true
      },
      "recovery": {
        "attempted": false,
        "successful": false,
        "discoveredVia": null,
        "sourceUri": null,
        "source": null,
        "confidence": null,
        "recoveredAt": null
      },
      "preserved": {
        "stored": false,
        "url": null,
        "contentHash": null,
        "status": "not_configured"
      },
      "diagnostics": [],
      "candidates": [],
      "lastCheckedAt": "2026-08-26T00:00:00.000Z",
      "timings": {}
    }
  }
}

Field names come from toPublicMediaResponse in the API. Nullable fields reflect unknown or not-yet-attempted recovery.

Concepts

Canonical vs best available

• **canonicalUri** — whatever normalized metadata reports (media.image). This is the on-chain/metadata truth.
• **bestAvailableUri** — best URI the reliability layer can serve when the canonical origin is broken.
• **preserved.url** — durable R2 copy when object storage is configured. Never treat this as the on-chain image URI.

Origin provider

origin.provider identifies how the canonical URI was classified (e.g. HTTPS, IPFS gateway, Arweave). This is **not** marketplace scraping — the engine does not depend on Orb, HowRare, or Magic Eden HTML.

Recovery and `discoveredVia`

When recovery runs, recovery.discoveredVia describes how an alternate candidate was found (e.g. IPFS gateway failover, Helius DAS media refs, or media_gateway for a supported image proxy/CDN). recovery.confidence is high, medium, or low per source semantics.

When MEDIA_PROXY_RECOVERY_USED appears in media diagnostics, a provider image proxy (for example Helius CDN transform) supplied reachable bytes after the canonical URI failed. The **canonical URI is preserved** as provenance; durable display prefers preserved.url (R2) when configured.

SHA-256 fingerprint

When content is validated or preserved, preserved.contentHash holds a SHA-256 hex digest of the image bytes. Identical bytes reuse the same object key in R2 (media/sha256/<hash>.<ext>).

Caching behavior

Media results are cached in Redis and persisted to the database. Successful validations and failures use separate TTLs (MEDIA_VALIDATION_TTL_SECONDS, MEDIA_RECOVERY_FAILURE_TTL_SECONDS). Use force=true or POST .../recover to bypass cache.

Monitoring limitation

Asset image monitor checks read **stored media-recovery state** rather than actively revalidating media on every monitor cycle. image.failed / image.recovered events may lag until media recovery runs or the asset is resolved elsewhere. See [monitoring.md](./monitoring.md).

Supported origins

SVG is not preserved (active content risk); canonical SVG URLs may still be reported.

See also [media-recovery.md](../media-recovery.md) for operational setup.