AI Integration Quickstart

This guide summarizes the machine-friendly endpoints, formats, and headers exposed by MainStreet.Club for LLM crawlers and retrieval systems.

Core Feeds

Endpoint	Format	Features
`/api/v1/feeds/index`	NDJSON	Supports `?since=`, ETag, gzip, CORS
`/api/v1/feeds/businesses`	NDJSON or JSON	Cursors, incremental sync, gzip, Last-Modified
`/api/v1/feeds/catalog`	NDJSON	Bulk export, gzip
`/ai-index.jsonl`	NDJSON	Incremental sync, conditional GET

Compression: gzip when clients send Accept-Encoding: gzip.
Caching: responses cache for 180 seconds with stale-while-revalidate=120.
Security: feeds include X-Frame-Options, X-Content-Type-Options, and Permissions-Policy.
CORS: Access-Control-Allow-Origin: * with exposed ETag, Last-Modified, and X-Next-Cursor.

Each entity bundles normalized verification metadata sourced from our VerificationMetadataService, including:

verification.isVerified, verification.level, and verification.lastVerifiedOn.
verification.confidence.score and verification.confidence.label.
Aggregate data_quality_score, source_credibility, and factual_accuracy.
JSON-LD exposes these via additionalProperty arrays for schema validators.

Business feed records expose a stable schema so retrievers and validators can map attributes quickly.

Field	Type	Notes
`id`	string (UUID)	Stable business identifier; use with `?cursor=` for pagination.
`name`	string	Display-ready business name, escaped UTF-8.
`url`	string (absolute URL)	Canonical landing page. Always HTTPS.
`primary_category`/`category`	string	Normalized taxonomy slug, e.g. `home-services`.
`city`, `province`, `country`	strings	Location context for filtering or geo weighting.
`verification`	object	Trust payload with `isVerified`, `level`, `lastVerifiedOn`, and `confidence`.
`products`	array	Top promoted listings per business when `include_products=true`.
`feed_timestamp`	ISO 8601	Combined value used for ordering and cursoring.

Feeds default to 50 items; override with ?limit= (max 200).
Clients should persist X-Next-Cursor and pass it back via ?cursor= for resumable sync.
Ordering is deterministic: GREATEST(updated_at, last_verified_on) then id (UUID string).
For incremental loads, append ?since=2025-10-01T00:00:00Z to both the index and feeds.

All endpoints emit Cache-Control: public, max-age=300, stale-while-revalidate=120.
Use ETag and Last-Modified to issue conditional GETs. Matching validators return 304 Not Modified.
X-AI-Response-Format announces the body type (ndjson, json, or html).
CORS responses expose X-Next-Cursor, ETag, and Last-Modified for browser-based agents.

Use /api/v1/ping for a lightweight capability check. It returns current versions, enabled compression, and important documentation links.

Email [email protected] for higher rate limits or integration questions.