Internet-Draft (informational, hosted)

    agent-preview/v1

    A vendor-neutral schema for one-fetch URL preview manifests.

    Spec version
    1.0
    MIME type
    application/vnd.agent-preview+json
    Normative spec
    /spec/agent-preview/v1
    Status
    Open invitation — adopt freely, no permission needed
    Publisher
    Mnemom (reference implementation)

    Abstract

    This document specifies agent-preview/v1, a JSON shape served as a sibling resource at <url>.preview.json alongside every page that would otherwise be a candidate for OpenGraph preview. The manifest gives an agent client a structured, typed summary of a URL — title, summary, canonical, MIME-tagged representations (HTML, markdown mirror, OG image, JSON-LD), and type-specific context — in a single fetch. Discovery is via <link rel="alternate" type="application/vnd.agent-preview+json"> in the source HTML's <head>.

    The intent is the OpenGraph equivalent for agentic clients: one fetch, structured, vendor-neutral. Any site can adopt the shape and publish manifests without Mnemom's permission or dependency.

    Status of this memo

    This is an informational draft hosted at https://www.mnemom.ai/spec/agent-preview/v1/rfc. The normative schema is at https://www.mnemom.ai/spec/agent-preview/v1. Mnemom hosts the canonical text and reference implementation, and commits to:

    • Keep the v1 schema additive — new fields are optional; consumers MUST tolerate additional keys and unknown type values (treat unknowns as reference).
    • Version through URL paths (/spec/agent-preview/v1, /v2, …); old URLs stay frozen indefinitely.
    • Verify our own conformance via the nightly preview-surface commitment on mnemom.ai/for-agents.

    If adoption materializes across multiple independent implementations, the MIME type is candidate for IANA registration in the Standards Tree (dropping the vnd. prefix); see IANA Considerations. Until then this is a vendor-tree entry per RFC 6838.

    Conventions

    The key words MUST, SHOULD, MAY, MUST NOT, and SHOULD NOT in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

    Motivation

    An agentic client fetching a URL faces three choices today:

    1. Fetch + render HTML: heavy. Most agents don't run a browser; the markdown mirror or OG meta is usually what they actually need.
    2. Fetch the markdown mirror (.md): useful for body content, but doesn't carry the page's structured metadata (type, grade, status, author).
    3. Fetch the OG image: a 1200×630 PNG. Not machine-readable in the structured sense.

    None of these is one-shot addressable. agent-preview/v1 fills the gap: a single JSON fetch returns title, summary, canonical, representations (with discovery URLs for the other three), and type-specific context (e.g. author / published_at / tags for blog posts, grade / score for reputation profiles).

    Schema (v1)

    The manifest is a single JSON object. The normative TypeScript interface is in client/lib/preview-types.ts. Required keys:

    {
  "spec_version": "1.0",            // String. Must equal "1.0" for v1.
  "spec_url": "...",                 // URL of this canonical spec.
  "url": "...",                      // The URL this preview is about.
  "canonical_url": "...",            // Preferred form for citing.
  "type": "blog_post",               // Type taxonomy; see below.
  "title": "...",                    // Short human-readable name.
  "summary": "...",                  // ≤ 220 chars recommended.
  "language": "en-US",               // BCP-47 language tag.
  "representations": {
    "html": "...",                   // Required.
    "markdown": "...",               // Optional (markdown mirror URL).
    "image": "https://www.mnemom.ai/api/og-image?type=blog&eyebrow=DISPATCHES&author=Mnemom+Research",
    "json_ld": "..."                 // Optional (JSON-LD source URL).
  },
  "context": { /* type-specific; empty object valid */ },
  "last_modified": "2026-05-13T00:00:00Z",
  "publisher": {
    "name": "...",
    "url": "...",
    "agents_txt": "...",
    "readiness_manifest": "..."
  }
}

    Type taxonomy (extensible; consumers MUST treat unknowns as reference): home, marketing, blog_post, research_paper, case_study, agent_profile, team_profile, methodology, explainer, policy, discovery, coherence_report, reference.

    Context fields (all optional, additive): eyebrow, author, published_at (ISO 8601), reading_time_min, tags (array), company, outcome, agent_id, team_id, grade, score (0–1000), last_attested_at, status, primitives (array).

    Discovery

    Sites MUST advertise availability via a <link rel="alternate"> element in the source page's <head>:

    <link rel="alternate" type="application/vnd.agent-preview+json" href="<url>.preview.json">

    Servers SHOULD respond to Accept: application/vnd.agent-preview+json requests on the source URL with a 303 redirect to the .preview.json sibling, but clients MUST NOT assume conneg is implemented — the discovery link is the canonical path.

    Servers MUST serve the manifest with Content-Type: application/vnd.agent-preview+json.

    Versioning

    v1 fields are conservative; new fields land additively in minor revisions (1.0 → 1.1 → 1.2). Schema-breaking changes require a new major path (/spec/agent-preview/v2). Old major versions stay frozen — adopters can pin spec_url and trust that the schema there will never change shape.

    Security considerations

    The preview JSON is public. Publishers MUST NOT include access-controlled data (private cards, claimed-only reports, signed payloads). For URLs that are noindex or otherwise gated, publishers either omit the manifest sibling entirely or serve a tombstone variant exposing only the fact of the URL's existence without sensitive context. Mnemom's implementation declines to write manifests for /r/<slug> (the coherence-report URLs are themselves the access-control mechanism).

    Caching: the manifest's last_modified is the stable source-of-truth timestamp. Clients SHOULD revalidate against If-Modified-Since. Manifests have no embedded freshness window beyond standard HTTP cache headers.

    IANA considerations

    The MIME type application/vnd.agent-preview+json is currently a vendor-tree entry per RFC 6838 §3.2. If interoperable use across multiple independent implementations is demonstrated, the registrant (Mnemom) will request promotion to the Standards Tree at application/agent-preview+json, retaining the same schema and discovery pattern. The version path stays at /spec/agent-preview/v1 through the rename.

    Until promotion, the vendor-tree entry is intentional and stable. Adopters can rely on the existing MIME for production use; the schema does not change as a function of registration status.

    Adoption

    The spec is intentionally vendor-neutral. Any site can adopt the shape, point at this hosted spec, and let its URLs become one-fetch addressable for agents — no Mnemom dependency, no permission needed. The reference implementation is open at github.com/mnemom/mnemom-website (see scripts/build-preview-cards.mjs).

    If you've shipped agent-preview manifests on a domain you control, we'd love to add you to the adopters list — open an issue at the repo above.

    References

    • RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels
    • RFC 8174 — Ambiguity of Uppercase vs Lowercase in 2119
    • RFC 6838 — Media Type Specifications and Registration Procedures
    • RFC 9110 — HTTP Semantics (content negotiation, conditional requests)
    • OpenGraph Protocol — ogp.me
    Featured on There's An AI For That