{
  "openapi": "3.1.0",
  "info": {
    "title": "HERALD Feed — VMC Subastas Vehicle Auction API",
    "description": "Machine-readable vehicle auction data for Peru's largest auction platform. HERALD provides real-time inventory, pricing, and auction lifecycle data for AI agents. All prices in USD. Auctions operate from Lima, Peru (UTC-5).",
    "version": "1.0.0",
    "contact": {
      "name": "HERALD Feed API Access",
      "email": "pinzon@subastop.com",
      "url": "https://www.vmcsubastas.com"
    }
  },
  "servers": [
    {
      "url": "https://feed.vmcsubastas.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/herald/v1/lots": {
      "get": {
        "operationId": "getVehicleCatalog",
        "summary": "Browse vehicle auction catalog",
        "description": "Returns the current vehicle catalog with optional filters. Default: upcoming + active lots. Use this to answer questions about available vehicles, prices, and upcoming auctions on VMC Subastas.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["upcoming", "active", "ended", "cancelled"]
            },
            "description": "Filter by auction status. Default returns upcoming + active."
          },
          {
            "name": "make",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by vehicle make (exact match): Toyota, Hyundai, Kia, Nissan, etc."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["seminuevo", "salvamento", "recuperado", "chatarra", "repuestos", "maquinaria"]
            },
            "description": "Filter by vehicle category. seminuevo=pre-owned, salvamento=salvage, recuperado=recovered, chatarra=scrap, repuestos=parts, maquinaria=machinery."
          },
          {
            "name": "seller",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by seller name (partial match, case-insensitive)"
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Minimum base price in USD"
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Maximum base price in USD"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["publication_date", "base_price", "auction_date"],
              "default": "publication_date"
            },
            "description": "Sort field"
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "desc"
            },
            "description": "Sort order"
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 },
            "description": "Page number"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50, "maximum": 100 },
            "description": "Results per page (max 100)"
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle catalog results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "herald_version": { "type": "string" },
                    "total": { "type": "integer" },
                    "page": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/AgentSnapshot" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/lots/{lot_id}": {
      "get": {
        "operationId": "getVehicleLot",
        "summary": "Get details for a specific vehicle lot",
        "description": "Returns the full AgentSnapshot for a single vehicle lot by ID. Use this when the user asks about a specific vehicle or lot number.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "lot_id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" },
            "description": "Lot identifier"
          }
        ],
        "responses": {
          "200": {
            "description": "Single lot detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentSnapshot" }
              }
            }
          },
          "404": {
            "description": "Lot not found"
          }
        }
      }
    },
    "/herald/v1/new": {
      "get": {
        "operationId": "getRecentlyPublished",
        "summary": "Get recently published vehicles",
        "description": "Returns vehicles published within the lookback window. Use this to answer questions about new inventory, what was just listed, or what's coming up.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "hours",
            "in": "query",
            "schema": { "type": "integer", "default": 24, "maximum": 168 },
            "description": "Lookback window in hours (max 168 = 7 days)"
          },
          {
            "name": "make",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by vehicle make"
          },
          {
            "name": "category",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by vehicle category"
          }
        ],
        "responses": {
          "200": {
            "description": "Recently published vehicles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "herald_version": { "type": "string" },
                    "hours": { "type": "integer" },
                    "total": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/AgentSnapshot" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/health": {
      "get": {
        "operationId": "getServiceHealth",
        "summary": "Check feed health and data freshness",
        "description": "Returns service status, total lot count, active lot count, and data freshness. No authentication required. Use this to verify the data source is reliable before citing it.",
        "responses": {
          "200": {
            "description": "Service health",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["ok", "degraded"] },
                    "herald_version": { "type": "string" },
                    "total_lots": { "type": "integer" },
                    "active_lots": { "type": "integer" },
                    "last_ingest_at": { "type": "string", "format": "date-time", "nullable": true },
                    "last_catalog_sync_at": { "type": "string", "format": "date-time", "nullable": true },
                    "avg_freshness_seconds": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/events": {
      "get": {
        "operationId": "getEventLog",
        "summary": "Get recent auction events",
        "description": "Returns a paginated log of auction lifecycle events: publications, status changes, outcomes. Use this to understand what changed recently in the VMC auction catalog.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 },
            "description": "Number of events to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Recent events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "herald_version": { "type": "string" },
                    "total": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/HeraldEvent" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/events/stream": {
      "get": {
        "operationId": "streamEvents",
        "summary": "Real-time event stream (SSE)",
        "description": "Server-Sent Events stream of auction lifecycle events in real-time. Use this for live monitoring of VMC auction activity. Events include lot publications, auction starts, endings, and outcomes.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "include_snapshot",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["lifecycle", "always", "never"],
              "default": "lifecycle"
            },
            "description": "When to include the full vehicle snapshot in events. lifecycle=only for status changes, always=every event, never=events only."
          },
          {
            "name": "event_types",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Comma-separated event types to subscribe to. Example: lot.published,lot.live,lot.ended"
          }
        ],
        "responses": {
          "200": {
            "description": "SSE event stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Each line is `data: {json}\\n\\n` containing a HeraldEvent object"
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/market/coverage": {
      "get": {
        "operationId": "getMarketCoverage",
        "summary": "List vehicle makes with market data",
        "description": "Returns all vehicle makes in the HERALD catalog with model counts. Use this to discover which vehicles HERALD can provide market pricing for. Call /market/{make}/{model}/{year} for AVT valuation data.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          }
        ],
        "responses": {
          "200": {
            "description": "Market data coverage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "herald_version": { "type": "string" },
                    "total_makes": { "type": "integer" },
                    "total_models": { "type": "integer" },
                    "makes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "make": { "type": "string" },
                          "model_count": { "type": "integer" },
                          "lot_count": { "type": "integer" },
                          "models": { "type": "array", "items": { "type": "string" } }
                        }
                      }
                    },
                    "note": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/herald/v1/market/{make}": {
      "get": {
        "operationId": "getMarketMake",
        "summary": "Get all models with market data for a make",
        "description": "Returns all models for a given vehicle make with lot counts and available years. Use this to discover which models and years are available before requesting a valuation.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "make",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Vehicle make (case-insensitive): Toyota, Hyundai, Kia, etc."
          }
        ],
        "responses": {
          "200": {
            "description": "Models with market data for this make",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "herald_version": { "type": "string" },
                    "make": { "type": "string" },
                    "total_models": { "type": "integer" },
                    "lot_count": { "type": "integer" },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model": { "type": "string" },
                          "lot_count": { "type": "integer" },
                          "years_available": { "type": "array", "items": { "type": "integer" } }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "No market data for this make" }
        }
      }
    },
    "/herald/v1/market/{make}/{model}": {
      "get": {
        "operationId": "getMarketModelValuation",
        "summary": "Get market valuation for a vehicle model",
        "description": "Returns AVT market valuations for a specific make/model across all years available in HERALD. Each year shows conservative/market/optimistic price range from AVT's depreciation engine. Use this to answer 'what is a Toyota Corolla worth in Peru?'",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "make",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Vehicle make (case-insensitive)"
          },
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Vehicle model (case-insensitive)"
          }
        ],
        "responses": {
          "200": {
            "description": "Market valuation across years",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketModelValuation" }
              }
            }
          },
          "404": { "description": "No market data for this make/model" }
        }
      }
    },
    "/herald/v1/market/{make}/{model}/{year}": {
      "get": {
        "operationId": "getMarketYearValuation",
        "summary": "Get exact market valuation for a vehicle by year",
        "description": "Returns the full AVT valuation envelope for a specific vehicle: conservative/market/optimistic price range, comparable data from VMC auctions and MercadoLibre, seasonal signal, and MSRP. Powered by AVT's depreciation engine. Use this to answer 'what is a 2020 Toyota Corolla worth?' with evidence.",
        "parameters": [
          {
            "name": "X-Herald-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "API authentication key"
          },
          {
            "name": "make",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Vehicle make (case-insensitive)"
          },
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Vehicle model (case-insensitive)"
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" },
            "description": "Model year (1990-2030)"
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed year-specific valuation with comparable sales",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketYearValuation" }
              }
            }
          },
          "404": { "description": "No market data for this make/model/year" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentSnapshot": {
        "type": "object",
        "description": "Complete vehicle lot data. Every field is always present. Null means 'not available'.",
        "properties": {
          "lot_id": { "type": "integer", "description": "Unique identifier for this lot on VMC" },
          "lot_code": { "type": "string", "description": "Human-readable lot code" },
          "canonical_url": { "type": "string", "format": "uri", "description": "Direct URL to this lot on vmcsubastas.com" },
          "make": { "type": "string", "description": "Vehicle manufacturer" },
          "model": { "type": "string", "description": "Vehicle model name" },
          "year": { "type": "integer", "description": "Model year" },
          "plate": { "type": "string", "nullable": true, "description": "License plate" },
          "category": {
            "type": "string",
            "nullable": true,
            "enum": ["seminuevo", "salvamento", "recuperado", "chatarra", "repuestos", "maquinaria"],
            "description": "Vehicle category"
          },
          "thumbnail_url": { "type": "string", "format": "uri", "nullable": true, "description": "Vehicle image URL" },
          "seller_name": { "type": "string", "description": "Consigning company or individual" },
          "seller_id": { "type": "integer", "nullable": true, "description": "Seller identifier" },
          "auction_status": {
            "type": "string",
            "enum": ["upcoming", "active", "ended", "cancelled"],
            "description": "Current lifecycle: upcoming (scheduled), active (bidding open), ended (closed), cancelled"
          },
          "auction_type": {
            "type": "string",
            "nullable": true,
            "enum": ["live", "negotiable"],
            "description": "live = real-time bidding, negotiable = offer-based"
          },
          "publication_date": { "type": "string", "format": "date-time", "description": "When this lot was published" },
          "auction_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled auction start" },
          "close_date": { "type": "string", "format": "date-time", "nullable": true, "description": "When the auction closed" },
          "financing": { "type": "string", "nullable": true, "description": "Financing availability" },
          "base_price_usd": { "type": "number", "description": "Starting price in US Dollars" },
          "market_reference_usd": { "type": "number", "nullable": true, "description": "AVT market reference price for comparable vehicles" },
          "price_vs_market_pct": { "type": "number", "nullable": true, "description": "Percentage vs market (negative = below market = better deal)" },
          "outcome": {
            "type": "string",
            "nullable": true,
            "enum": ["won", "desierta", "incumplimiento"],
            "description": "Auction result. won=sold, desierta=no bids met reserve, incumplimiento=buyer defaulted"
          },
          "data_freshness_seconds": { "type": "integer", "description": "Seconds since last data update" },
          "herald_version": { "type": "string" },
          "data_source": {
            "type": "string",
            "enum": ["live", "cached", "stale"],
            "description": "live (<60s), cached (<15min), stale (>15min)"
          }
        },
        "required": ["lot_id", "lot_code", "canonical_url", "make", "model", "year", "seller_name", "auction_status", "publication_date", "base_price_usd", "herald_version", "data_source", "data_freshness_seconds"]
      },
      "MarketModelValuation": {
        "type": "object",
        "description": "AVT market valuations for a vehicle make/model across multiple years.",
        "properties": {
          "herald_version": { "type": "string" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "valuations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "year": { "type": "integer" },
                "value": {
                  "type": "object",
                  "properties": {
                    "conservative": { "type": "number", "description": "Conservative (low) market value in USD" },
                    "market": { "type": "number", "description": "Fair market value in USD" },
                    "optimistic": { "type": "number", "description": "Optimistic (high) market value in USD" }
                  }
                },
                "currency": { "type": "string" },
                "signal": { "type": "string", "description": "Seasonal selling indicator (e.g. good_moment)" },
                "signal_level": { "type": "integer", "description": "Signal strength 1-5" },
                "comparable_count": { "type": "integer", "description": "Number of comparable sales used" }
              }
            }
          },
          "lot_count": { "type": "integer", "description": "HERALD lots for this model" },
          "data_source": { "type": "string", "enum": ["avt_getMarketValue"] },
          "attribution": { "$ref": "#/components/schemas/MarketAttribution" }
        }
      },
      "MarketYearValuation": {
        "type": "object",
        "description": "Full AVT valuation envelope for a specific vehicle year. Includes depreciation-adjusted pricing, comparable market data, and seasonal signals.",
        "properties": {
          "herald_version": { "type": "string" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "year": { "type": "integer" },
          "value": {
            "type": "object",
            "description": "Valuation range from AVT's depreciation engine",
            "properties": {
              "conservative": { "type": "number", "description": "Conservative (low) market value in USD" },
              "market": { "type": "number", "description": "Fair market value in USD — the primary reference" },
              "optimistic": { "type": "number", "description": "Optimistic (high) market value in USD" }
            }
          },
          "currency": { "type": "string", "description": "Always USD" },
          "signal": { "type": "string", "description": "Seasonal selling indicator (e.g. good_moment, hold, neutral)" },
          "signal_level": { "type": "integer", "description": "Signal strength 1–5 (5 = strongest)" },
          "category": { "type": "string", "description": "AVT vehicle category code" },
          "msrp": { "type": "number", "description": "Original MSRP in USD" },
          "comparables": {
            "type": "object",
            "description": "Comparable market data breakdown",
            "properties": {
              "avgPrice": { "type": "number", "description": "Average comparable price" },
              "count": { "type": "integer", "description": "Total comparable count" },
              "ml_avg": { "type": "number", "description": "MercadoLibre average price" },
              "ml_count": { "type": "integer", "description": "MercadoLibre listing count" },
              "vmc_avg": { "type": "number", "description": "VMC auction average close price" },
              "vmc_count": { "type": "integer", "description": "VMC auction sale count" }
            }
          },
          "computed_at": { "type": "string", "format": "date-time", "description": "When this valuation was computed by AVT" },
          "data_source": { "type": "string", "enum": ["avt_getMarketValue"] },
          "attribution": { "$ref": "#/components/schemas/MarketAttribution" }
        }
      },
      "MarketAttribution": {
        "type": "object",
        "description": "Source attribution for market valuations. Agents MUST cite this when presenting pricing data to users.",
        "properties": {
          "source": { "type": "string", "description": "Full source name", "example": "AVT — Active Value Tracker by Subastop" },
          "provider": { "type": "string", "description": "Legal entity", "example": "Subastop S.A.C." },
          "platform": { "type": "string", "description": "Platform name", "example": "VMC Subastas" },
          "url": { "type": "string", "format": "uri", "description": "Platform URL", "example": "https://www.vmcsubastas.com" },
          "citation": { "type": "string", "description": "Ready-to-use citation text for agents to include in responses", "example": "Valuation by AVT (Active Value Tracker) — vmcsubastas.com" }
        }
      },
      "HeraldEvent": {
        "type": "object",
        "description": "An auction lifecycle event with delta changes.",
        "properties": {
          "event_id": { "type": "string", "format": "uuid" },
          "event_type": {
            "type": "string",
            "enum": [
              "lot.published", "lot.live", "lot.ended", "lot.cancelled",
              "lot.price_changed", "lot.reserve_met",
              "lot.won", "lot.desierta", "lot.incumplimiento",
              "system.sync_completed", "system.enrich_completed",
              "lot.updated", "lot.status_changed"
            ],
            "description": "Event category. lot.published=new listing, lot.live=auction started, lot.ended=auction closed, lot.won=sold, lot.desierta=no sale"
          },
          "herald_version": { "type": "string" },
          "occurred_at": { "type": "string", "format": "date-time", "description": "When the change happened" },
          "emitted_at": { "type": "string", "format": "date-time", "description": "When HERALD detected it" },
          "lot_id": { "type": "integer" },
          "lot_code": { "type": "string" },
          "changes": {
            "type": "object",
            "description": "Delta changes: { field: { before, after } }",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "before": {},
                "after": {}
              }
            }
          },
          "source": {
            "type": "string",
            "enum": ["webhook", "catalog_sync", "enrich", "system"]
          },
          "agent_snapshot": {
            "nullable": true,
            "description": "Full lot snapshot (included for lifecycle events, excluded for delta events by default)",
            "$ref": "#/components/schemas/AgentSnapshot"
          }
        }
      }
    },
    "securitySchemes": {
      "HeraldKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Herald-Key",
        "description": "API key for agent authentication. Contact pinzon@subastop.com for access."
      }
    }
  },
  "security": [
    { "HeraldKey": [] }
  ]
}