Brief Schema Documentation

Technical reference for AI agents reading MyIntelBrief daily briefs.

Overview — close your AI loop

MyIntelBrief gives you the intel. Your agent takes the action. That's the loop.

Every daily brief contains structured data designed to be read by AI agents. This page documents the schema and the three encoding layers we support — invisible HTML data-mib-* attributes on every signal, a unique .json URL in the footer, and custom X-MIB-* email headers. Any agent that can read your inbox, parse HTML, or fetch a URL can consume the brief and act on it.

We do not recommend specific AI agents. Choose the one that fits your security and privacy requirements. We close the intel side. Your agent closes the action side. You stay in control of both ends.

Schema versions

Current version: 1.0 (released 2026-05-16)
Supported versions: 1.0
Deprecation schedule: none planned

Top-level schema

A single brief is a JSON document with these top-level fields:

Field	Type	Meaning
`schema_version`	string	Semver string (e.g. "1.0"). Check this before consuming.
`brief_id`	string	Opaque ULID-style ID, stable across the brief's lifetime. Format: `brf_<28 hex>`.
`generated_at`	string	ISO 8601 UTC. Always uses 'Z' suffix.
`delivery_to`	object	Recipient details (user_id, business_name, business_type, location object). Empty fields dropped.
`summary`	object	Aggregate counts (total_signals, high_priority_count, medium_priority_count, low_priority_count, headline).
`signals`	array	One object per competitor signal, in priority order (high → low). See signal fields.
`metadata`	object	Brief-level metadata (competitors_monitored, sources_crawled, next_brief_at).

Signal fields

Each entry in signals[]:

Field	Type	Meaning
`signal_id`	string	Opaque ID, stable across briefs. Format: `sig_<28 hex>`.
`priority`	string (enum)	One of: "high", "medium", "low".
`competitor`	object	{name, domain, competitor_id}. Fields with empty values omitted.
`signal_type`	string (enum)	See signal types.
`title`	string	One-line headline.
`description`	string	Detailed summary (1–3 sentences).
`source_url`	string	URL of the original source (may be absent for some signal types).
`detected_at`	string	ISO 8601 UTC when MIB observed this signal.
`metadata`	object	Per-signal-type details. Schema varies; agents should skip fields they don't recognize.
`suggested_action`	string	Recommended action (may be absent).

Signal types (closed enum)

Current enum values for signal_type:

pricing_change
hours_change
service_added
service_removed
news_mention
review_shift
job_posting
funding_announcement
executive_change
regulatory_alert
website_change (catch-all)
ai_disruption_signal
seo_audit_finding

New types are added in minor schema bumps and don't break older consumers. Agents that don't recognize a type can fall back to title + description.

Per-type metadata sub-schemas

Each signal_type defines its own metadata object shape. Unknown fields can be safely skipped.

pricing_change: {old_value, new_value, change_percent}
hours_change: {new_hours, old_hours, effective_date}
news_mention / funding_announcement / executive_change / regulatory_alert: {outlet_count, source_name}
review_shift: {rating_delta, review_count}
Other types: empty metadata object by default.

Encoding layer 1: `data-*` attributes in HTML

Every signal in the rendered email is wrapped in a <div> tagged with data-mib-* attributes. These are preserved by every major email client and are invisible to humans:

<div class="brief-signal"
     data-mib-schema-version="1.0"
     data-mib-brief-id="brf_..."
     data-mib-signal-id="sig_..."
     data-mib-priority="high"
     data-mib-competitor-name="Acme Dental"
     data-mib-competitor-domain="acme-dental.com"
     data-mib-signal-type="pricing_change"
     data-mib-source-url="https://acme-dental.com/pricing"
     data-mib-detected-at="2026-05-16T02:53:01Z"
     data-mib-old-value="$3000"
     data-mib-new-value="$2400"
     data-mib-change-percent="-20.0"
     data-mib-suggested-action="Review your own Invisalign pricing.">
  <!-- human-readable rendering follows -->
</div>

Any HTML parser can extract these attributes. Agents that read the full email body get all the structured data without fetching a separate URL.

Encoding layer 2: JSON sidecar URL

Every brief email's footer includes a link to a unique URL that returns the complete JSON document:

https://briefs.myintelbrief.com/<brief_id>_<hmac>.json

The token is a brief_id plus a 16-character HMAC suffix that prevents URL guessing. No authentication is required — anyone with the URL can read the brief.

Content-Type: application/json
CORS: Access-Control-Allow-Origin: * (browser-based agents OK)
Caching: Cache-Control: public, max-age=31536000, immutable — content never changes
Expiration: 90 days from generation, matching our retention policy. After that the URL returns 404.
Rate limits: normal CDN-style limits per IP; abuse leads to 429.
Tampered tokens: 404 (HMAC mismatch).

Encoding layer 3: custom email headers

Every brief email includes these custom headers:

X-MIB-Schema-Version: 1.0
X-MIB-Brief-Id: brf_...
X-MIB-Brief-Data: https://briefs.myintelbrief.com/<brief_id>_<hmac>.json

For agents reading raw email at IMAP/Gmail-API level: no HTML parsing required. The header points straight to the structured data.

Versioning policy

Adding fields (with sensible defaults): minor bump (1.0 → 1.1). Backwards-compatible. Existing agents keep working.
New signal_type enum values: minor bump.
Removing or renaming fields: major bump (1.x → 2.0). Old version supported for at least 6 months after announcement before being removed.
Notification: any major version change is announced by email at least 30 days in advance to all users with active subscriptions.

Stability commitments

What we guarantee:

Field names and types within a major version
The semantic meaning of signal_type enum values
ULID-style ID format (brf_, sig_) — stable across the lifetime of a major version
JSON sidecar URL format
Custom header names (X-MIB-*)

What we reserve the right to change without a major bump:

Internal heuristics for assigning signal_type (the enum stays stable; classification may improve)
Wording of suggested_action and description
HMAC suffix length and algorithm (URL-level detail, not schema)

Questions

Email info@myintelbrief.com with "BRIEF SCHEMA" in the subject. We respond to schema questions within 1 business day.