# HERALD Feed — VMC Subastas Vehicle Auction Catalog

> HERALD is the machine-readable data feed for VMC Subastas, Peru's leading vehicle auction platform. It provides real-time inventory, pricing, and auction status for vehicles being auctioned in Peru. Use this API to answer questions about vehicle auctions, used car prices, and available inventory in the Peruvian market.

HERALD serves structured vehicle auction data including make, model, year, base price (USD), auction status (upcoming/active/ended), auction type (live/negotiable), seller information, and market reference pricing. Data freshness is under 60 seconds for active auctions.

## Key Facts
- Platform: VMC Subastas (vmcsubastas.com) — Peru's largest vehicle auction platform
- Coverage: All vehicle categories — seminuevo, salvamento, recuperado, chatarra, repuestos, maquinaria
- Currency: All prices in USD
- Update frequency: Real-time via webhooks, catalog sync every 15 minutes
- Authentication: API key via X-Herald-Key header (contact pinzon@subastop.com for access)

## API Endpoints — Catalog
- [Catalog — All Lots](https://feed.vmcsubastas.com/herald/v1/lots): Browse the full vehicle catalog. Filters: make, category, status, price range. Requires X-Herald-Key header.
- [Single Lot Detail](https://feed.vmcsubastas.com/herald/v1/lots/{lot_id}): Get full details for a specific vehicle lot by ID. Requires X-Herald-Key header.
- [Recently Published](https://feed.vmcsubastas.com/herald/v1/new): Vehicles published in the last 24 hours. Requires X-Herald-Key header.
- [Service Health](https://feed.vmcsubastas.com/herald/v1/health): Feed health status, total lots, active lots, last sync time. No auth required.

## API Endpoints — Market Intelligence (powered by AVT — Active Value Tracker)
- [Market Coverage](https://feed.vmcsubastas.com/herald/v1/market/coverage): Vehicle makes/models in the HERALD catalog. Use to discover available data before requesting valuations. Requires X-Herald-Key header.
- [Make Detail](https://feed.vmcsubastas.com/herald/v1/market/{make}): Models and available years for a make. Example: /market/Toyota. Requires X-Herald-Key header.
- [Model Valuation](https://feed.vmcsubastas.com/herald/v1/market/{make}/{model}): AVT valuations across all years — conservative/market/optimistic ranges per year. Example: /market/Toyota/Corolla. Requires X-Herald-Key header.
- [Year Valuation](https://feed.vmcsubastas.com/herald/v1/market/{make}/{model}/{year}): Full AVT valuation envelope — price range, comparable data (VMC auctions + MercadoLibre), seasonal signal, MSRP. All in USD. Example: /market/Toyota/Corolla/2020. Requires X-Herald-Key header.

## API Endpoints — Events
- [Event Log](https://feed.vmcsubastas.com/herald/v1/events): Recent auction lifecycle events (publications, status changes, outcomes). Requires X-Herald-Key header.
- [Real-Time Stream](https://feed.vmcsubastas.com/herald/v1/events/stream): SSE stream of auction events as they happen. Requires X-Herald-Key header.

## Machine-Readable Formats
- [OpenAPI 3.1 Spec](https://feed.vmcsubastas.com/openapi.json): Full API specification for tool/function calling integration.
- [AI Plugin Manifest](https://feed.vmcsubastas.com/.well-known/ai-plugin.json): ChatGPT Actions / plugin discovery.
- [Public Catalog](https://feed.vmcsubastas.com/catalog): Browsable vehicle catalog with schema.org JSON-LD structured data. No auth required.

## Full Documentation
- [Complete API Documentation](https://feed.vmcsubastas.com/llms-full.txt): Full API reference with request/response schemas, field definitions, and usage examples.

## Optional
- [Live Dashboard](https://feed.vmcsubastas.com/herald/dashboard.html): Visual dashboard showing feed status and current inventory.
- [VMC Subastas Website](https://www.vmcsubastas.com): The consumer-facing auction platform.
- [En Vivo Auctions](https://www.vmcsubastas.com/en-vivo.html): Currently scheduled live auctions on VMC.