Trail Bundle Format (`blincr-trail-bundle/1`)

The trail bundle is blincr's stable, agent-ready export format. It is what a user hands to their AI assistant (Claude, Cowork, or any other agent) when they want it to work with a browsing trail. If you are building an agent, plugin, or automation that consumes blincr data, parse this format — it is versioned and will not change shape within a major version.

Where bundles come from

Source	Action	Works for
Extension side panel	"For AI" button on a trail in the library	Every trail — built client-side, so encrypted tiers included
Dashboard `/my/trails`	"For AI" button per trail	Plaintext tiers (t3 / t3_self) — built server-side from the synced copy
API	`GET /api/user/trails/:id/bundle` (authenticated)	Same as dashboard

Downloads are named <title>.blincr-ai.json.

Top-level shape

{
  "schema": "blincr-trail-bundle/1",
  "generatedAt": "2026-07-10T15:00:00.000Z",
  "trail": {
    "id": "…",
    "title": "Jacket research",
    "category": "shopping",
    "tags": ["winter"],
    "description": "…",
    "createdAt": "2026-07-09T20:12:00.000Z",
    "durationMs": 742000,
    "stats": { "sites": 3, "pages": 7, "events": 42, "notes": 2, "selections": 1 },
    "events": [ … ]
  },
  "digest": "# Jacket research\n\n3 sites · 7 pages · …"
}

schema — always check this first. blincr-trail-bundle/1 is the current version; reject unknown majors.
trail.events — the full raw capture, unabridged. Every event has { type, url?, timestamp, payload }. Event types include navigation, page_info, click, scroll, selection, note, waypoint, clipboard, overlay.
digest — a compact Markdown summary designed for LLM context windows. If you only need the gist, use the digest and skip the events.
All optional metadata fields (id, category, tags, description, createdAt, durationMs) may be absent — treat them as optional.

The digest

The digest is deterministic Markdown built from the events:

# Jacket research

3 sites · 7 pages · 42 events · 12m 22s · shopping · captured 2026-07-09

## Pages visited

### shop.example
- **Winter Jackets** — 2m 10s, 5 interactions
  https://shop.example/jackets

## Notes
- Good fit

## Selections
> Patagonia Nano Puff

Bounds (so the digest stays token-cheap): 200 pages, 20 notes, 20 selections. When truncated, the digest says so and points at trail.events for the rest. Dwell per page is the time until the next navigation; the last page falls back to its final captured event.

Guarantees

Versioned: breaking changes bump the schema string (blincr-trail-bundle/2); additive optional fields do not.
Self-contained: no URLs to fetch, no auth needed — the file is the data. Safe to attach to an agent session or paste into a chat.
One builder: extension, dashboard, and API all use the same code (extension/src/trail-bundle.ts), so output is identical across sources for the same trail.

Consuming from an MCP client

If you are already connected to blincr's MCP endpoint (POST /mcp, see Backend API § MCP), the get_trail tool returns a JSON digest with the same bounds — use the bundle download when you need the full raw events.

Recipe: alert → agent handoff

A blincr (standing page watcher) can hand its alert straight to an agent, trail context included. The chain:

blincr fires → blincr.alert webhook → your automation → agent session

Configure the webhook. Settings → Webhooks: set your automation's catch-hook URL (Zapier, Make, n8n, or your own worker) and enable it. Deliveries are signed (X-Blincr-Signature, HMAC-SHA256, t=<unix>,v1=<hex> over <t>.<rawBody>).
Receive blincr.alert. The payload carries the full alert context — label, pageUrl, comparator, oldValue, newValue, message — and, when the blincr was created from a trail ("blincr this element" during a recorded session), the anchor trail: trailToken + trailUrl.
Attach the trail. Your automation fetches the agent-ready bundle for context: GET /api/user/trails/:id/bundle with an MCP token (Authorization: Bearer <token>, minted in Settings → AI agent access), or fetches the public trail page at trailUrl if the trail is published.
Start the agent session. Post the alert message + bundle digest into your agent (Claude, Cowork, or any MCP client). A connected MCP client can instead call list_blincr_alerts and get_trail itself — the webhook is then just the wake-up signal.

Example automation prompt for the agent session:

The price watcher "{{label}}" fired: {{message}} on {{pageUrl}}. Attached is the browsing trail that led to this watcher (blincr trail bundle, schema blincr-trail-bundle/1). Review what changed, compare with the trail context, and recommend whether to act.

The machine-readable event catalog (all events + payload shapes) is served at GET /api/public/integrations/webhooks.

Trail Bundle Format (blincr-trail-bundle/1)