> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# agent-preview/v1 Specification
> Normative spec for the agent-preview/v1 URL preview manifest: a structured JSON sibling for every URL, discoverable via . MIME application/vnd.agent-preview+json. Mnemom is the reference implementation; the spec is vendor-neutral.
A structured JSON manifest sibling for every URL. One fetch gives an agent the title, summary, type, representations (HTML, markdown, image, JSON-LD), and per-type context — without rendering HTML or parsing markdown.
Mnemom is the reference implementation of this spec. The schema is **vendor-neutral**: other sites can adopt the same shape, point at this hosted spec, and let their own URLs become one-fetch addressable for agents. As adoption grows the MIME can be IANA-registered to drop the `vnd.` prefix.
The canonical hosted copy of this spec is at [https://www.mnemom.ai/spec/agent-preview/v1/](https://www.mnemom.ai/spec/agent-preview/v1/) (this docs page mirrors it).
## Why
Pasting a URL in chat already produces a rich human preview (the OG image). For agents, the equivalent today is "fetch HTML, parse it, hope the meta tags are present and consistent." That's expensive and brittle. `agent-preview/v1` is the structured sibling — a one-fetch typed summary so agents previewing a link can decide whether to dig deeper before reading the full page or the markdown mirror.
## How discovery works
Every prerendered URL on a compliant site exposes a sibling preview manifest, advertised via `` in ``. Crawlers and humans ignore the unknown MIME; aware agents follow the link — they do not need to construct the sibling path themselves, but the general convention is: a URL ending in `/` gets an `index.preview.json` appended (`https://example.com/methodology/` → `https://example.com/methodology/index.preview.json`); a URL not ending in `/` gets a `.preview.json` suffix instead (`https://example.com/methodology` → `https://example.com/methodology.preview.json`). The site root follows the trailing-slash rule (`/` → `/index.preview.json`).
```html theme={null}
```
### MIME type
```text theme={null}
application/vnd.agent-preview+json
```
## Schema (v1.0)
The manifest is a single JSON object. Required keys are below; consumers MUST tolerate additional keys and unknown `type` values (treat unknowns as `reference`).
```json theme={null}
{
"spec_version": "1.0",
"spec_url": "https://www.mnemom.ai/spec/agent-preview/v1/",
"url": "https://www.mnemom.ai/methodology/",
"canonical_url": "https://www.mnemom.ai/methodology/",
"type": "methodology",
"title": "Mnemom Trust Rating™ Methodology",
"summary": "Fully transparent formula, component weights, grade scale.",
"language": "en-US",
"representations": {
"html": "https://www.mnemom.ai/methodology/",
"markdown": "https://www.mnemom.ai/methodology/index.md",
"image": "https://www.mnemom.ai/api/og-image?type=methodology",
"json_ld": "https://www.mnemom.ai/methodology/"
},
"context": {},
"last_modified": "2026-05-13T00:00:00Z",
"publisher": {
"name": "Mnemom",
"url": "https://www.mnemom.ai",
"agents_txt": "https://www.mnemom.ai/agents.txt",
"readiness_manifest": "https://www.mnemom.ai/for-agents/"
}
}
```
### Required fields
| Field | Type | Notes |
| - | - | - |
| `spec_version` | `"1.0"` | Spec version string. v1 == "1.0". |
| `spec_url` | string | Canonical URL of the published spec. Consumers can fetch this to validate they understand the version. |
| `url` | string | The URL this preview is *about*. Absolute http(s). |
| `canonical_url` | string | Preferred form for citing. Equals `url` for unambiguous routes; may differ for locale-prefixed paths that share an x-default canonical. |
| `type` | enum | See type taxonomy below. |
| `title` | string | Short human-readable name for the resource. |
| `summary` | string | One-line description. ≤ 220 chars recommended for previews. |
| `language` | string | BCP-47 language tag (en-US, fr-FR, …). |
| `representations` | object | Other URLs the agent can fetch for richer data. |
| `context` | object | Type-specific context. Empty object is valid. |
| `last_modified` | string | ISO 8601 timestamp; same source as sitemap.xml's lastmod. |
| `publisher` | object | Pointer to the issuing site's agent-readiness manifest. |
### type taxonomy
| Value | Meaning |
| - | - |
| `home` | Site root. |
| `marketing` | Generic marketing page (catch-all for top-level pages). |
| `blog_post` | An article in a chronological blog feed. |
| `research_paper` | A long-form research artifact (paper, whitepaper). |
| `case_study` | Customer/deployment narrative. |
| `agent_profile` | Public profile page for an AI agent. |
| `team_profile` | Public profile page for a team of agents. |
| `methodology` | Documented methodology or formula. |
| `explainer` | Conceptual explainer or how-it-works page. |
| `policy` | Legal/policy page (privacy, terms, etc.). |
| `discovery` | Agent-readability discovery surface (agents.txt host page, spec pages). |
| `coherence_report` | Mnemom-specific: a coherence report awaiting attestation. |
| `reference` | Catch-all. Consumers MUST treat unknown `type` values as this. |
### representations
```jsonc theme={null}
{
"html": "https://...", // required
"markdown": "https://....md", // optional (omit if route has no )
"image": "https://.../og.png", // required
"json_ld": "https://..." // optional (consumer extracts JSON-LD from this URL's HTML)
}
```
### context
Type-specific fields. All optional. Examples:
| Type | Fields |
| - | - |
| `blog_post` · `research_paper` | `author`, `published_at`, `reading_time_min`, `tags[]`, `eyebrow` |
| `case_study` | `company`, `outcome`, `eyebrow` |
| `agent_profile` · `team_profile` | `agent_id` / `team_id`, `grade`, `score`, `last_attested_at` |
| `coherence_report` | `status`, `primitives[]` |
Consumers MUST ignore unknown context fields and MUST NOT fail if `context` is `{}`.
### publisher
```jsonc theme={null}
{
"name": "Mnemom", // required
"url": "https://www.mnemom.ai", // required
"agents_txt": "https://www.mnemom.ai/agents.txt", // required
"readiness_manifest": "https://www.mnemom.ai/for-agents/" // required
}
```
The `readiness_manifest` URL SHOULD return a public document describing the site's agent-readability commitments. For Mnemom this is the page rendered from [agent-readiness.yaml](https://www.mnemom.ai/for-agents/).
## Versioning
Future schema changes go to v2 with a new MIME (`application/vnd.agent-preview+json; version=2`) and a new spec URL (`/spec/agent-preview/v2`). v1 stays frozen at its URL forever. Consumers can pin to `spec_url` + `spec_version` for stable behavior. Within v1, the schema is **append-only**: new optional fields can be added; existing field names and semantics MUST NOT change.
## Adopting on your site
If you publish marketing or content URLs that agents might encounter:
1. **Generate a preview-manifest sibling at build time** for every public URL, following the path convention in [How discovery works](#how-discovery-works) above. Walk your prerendered HTML, extract title / description / canonical / og:image, classify the type, write the manifest.
2. **Emit the ``** in every page's ``:
```html theme={null}
```
3. **Serve the file with the right Content-Type** (`application/vnd.agent-preview+json` is preferred; `application/json` is acceptable for CDNs that strip vendor MIMEs).
4. **Write a verifier** that validates your manifests against the v1 schema and runs in CI.
5. **Cross-reference from your `/agents.txt`**:
```
agent-preview-spec: https://www.mnemom.ai/spec/agent-preview/v1/
agent-preview-mime: application/vnd.agent-preview+json
agent-preview-discovery: # is the page's trailing-slash URL, e.g. /methodology/index.preview.json
agent-preview-example: https://yoursite.com/methodology/index.preview.json
```
## Compliance + reference implementation
Mnemom verifies the surface nightly. The live status is at [https://www.mnemom.ai/agent-readiness-status.json](https://www.mnemom.ai/agent-readiness-status.json) (`preview-surface` commitment). The public commitment renders on [/for-agents](https://www.mnemom.ai/for-agents/).
Mnemom's own implementation covers the full round-trip: a build-time generator that writes each route's manifest, a discovery emitter that adds the `` tag, and a CI verifier that checks every manifest against this schema before deploy.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.