HTTP API reference

Make a request

Base URL: https://zero-km.vercel.app/api/v1. Version 1.0.0. Use GET for queries; HEAD and OPTIONS are also supported. All responses are JSON and allow cross-origin browser access.

const query = new URLSearchParams({
  kind: 'price_drops', window: '7d',
  type: 'SUV', maxPriceUsd: '30000'
});
const response = await fetch(`https://zero-km.vercel.app/api/v1/deals?${query}`);
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
for (const car of body.data.vehicles) {
  console.log(car.currentPriceUsd, car.bestQuote, car.url);
}

GET /api/v1/deals

MCP tool find_deals

Find new-car buying opportunities in Argentina by budget, model and specs: below-usual prices, price drops in the last 1/3/7 days, or newly qualifying deals. Returns reasons, before/after prices where available, quote dates and links to explore on Zero KM.

• Shared filters ↗
• Pagination ↗

GET /api/v1/models/prices

MCP tool get_model_prices

Get current prices for an exact make and model in Argentina: starting price, cheapest version and quote, price range, opportunity count and versions ordered by price. Follow the model link for charts and detailed exploration.

curl --get 'https://zero-km.vercel.app/api/v1/models/prices' \
  --data-urlencode 'make=CITROEN' \
  --data-urlencode 'model=BASALT'

• Pagination ↗

GET /api/v1/vehicles

MCP tool search_vehicles

Find the lowest current new-car prices in Argentina by budget, make, model and sourced specifications. Defaults to cheapest first. For recent price drops and buying opportunities use find_deals; get_vehicle provides all current quotes.

• Shared filters ↗
• Pagination ↗

GET /api/v1/vehicles/{id}

MCP tool get_vehicle

Inspect a version’s current dealer cash quotes in original ARS/USD, fees, stock at observation, quote-check dates and official specification sources. Includes compact opportunity evidence and a Zero KM link for the full chart and saved shortlist.

GET /api/v1/compare

MCP tool compare_vehicles

Compare two to four versions by current prices, buying signals and sourced specifications. Returns a shareable Zero KM comparison page. Missing specifications remain unknown.

GET /api/v1/catalogue

MCP tool get_catalogue

Discover supported makes, models, filter values, coverage counts and snapshot dates before narrowing a price or opportunity search.

Shared search filters

Available on /deals and /vehicles. Names match without case or accents; other enum values are case-sensitive. q matches every word across make, model and version. Specification filters exclude unknown values.

Pagination and ordering

• Follow pagination.nextOffset until null. total counts all matches before paging. Model price ranges and opportunity counts always cover the full model, even when its versions are paginated.
• Search and model prices start with the cheapest versions. Deals use recommended: discount for current opportunities, percentage reduction for price drops, recency for new opportunities. Ties use a stable vehicle ID; deals and model lists also break ties by price.
• Unknown or insufficient-history discounts sort last. If snapshotAt changes between pages, restart at offset 0 when you need a consistent snapshot.

Response fields

Every query returns schemaVersion, snapshotAt, catalogueObservedAt, source, methodologyUrl, documentationUrl and data. Response schemas are defined in OpenAPI.

{
  "schemaVersion": 1,
  "snapshotAt": "2026-10-19T23:09:08.196Z",
  "catalogueObservedAt": "2026-10-19T23:05:15.913Z",
  "source": "https://elcerokm.com",
  "methodologyUrl": "https://zero-km.vercel.app/metodologia",
  "documentationUrl": "https://zero-km.vercel.app/developers",
  "data": {
    "kind": "price_drops",
    "window": "7d",
    "vehicles": [
      {
        "id": "ASqaWO3KfV4tWT3pjkv3B",
        "url": "https://zero-km.vercel.app/renault/kardian/iconic-200-edc",
        "feedUrl": "https://zero-km.vercel.app/datos/renault/kardian/iconic-200-edc.json",
        "make": "RENAULT",
        "model": "KARDIAN",
        "trim": "ICONIC 200 EDC",
        "trimDisplay": "Iconic 200 EDC",
        "type": "SUV",
        "tier": "Entry",
        "tierLabel": "Entrada de gama",
        "fuel": "Petrol",
        "transmission": "Automatic",
        "seats": 5,
        "airbags": 6,
        "factSources": {
          "fuel": "official",
          "transmission": "official",
          "seats": "catalogue",
          "airbags": "catalogue"
        },
        "observedAt": "2026-10-18T20:04:03.490Z",
        "currentPriceUsd": 27837.867549668874,
        "comparison": {
          "windowDays": 180,
          "typicalPriceUsd": 29513.88888888889,
          "lowestPriceUsd": 27186.801346801345,
          "discountPct": 5.678754655239581,
          "observedWeeks": 9,
          "sufficientHistory": true,
          "opportunity": true
        },
        "sourceUrl": "https://elcerokm.com/renault/kardian/iconic-200-edc",
        "recentChanges": {
          "1d": null,
          "3d": null,
          "7d": {
            "kind": "new_opportunity",
            "changedAt": "2026-10-13T21:05:09.856Z",
            "qualifiedSince": null,
            "dropPct": 15.011767084512739,
            "previousPriceUsd": 32754.96688741722,
            "currentPriceUsd": 27837.867549668874,
            "conversionBasis": "current_observed_exchange_rate"
          }
        },
        "hasSpecs": true,
        "quoteCount": 2,
        "bestQuote": {
          "id": 44037,
          "price": 42035180,
          "currency": "ARS",
          "priceUsd": 27837.867549668874,
          "feesIncluded": true,
          "color": null,
          "stock": 1,
          "location": null,
          "sellerId": null
        },
        "availability": "InStock",
        "reasons": [
          "below_typical",
          "price_drop",
          "new_opportunity"
        ]
      }
    ],
    "pagination": {
      "total": 4,
      "limit": 1,
      "offset": 0,
      "nextOffset": 1
    }
  }
}

• Price signals, dates and currencies ↗
• Full response schemas ↗

Caching and errors

Successful queries include an ETag and a five-minute shared-cache lifetime. Send If-None-Match to get 304 for an unchanged response. Errors are not cached. Reuse responses, paginate and back off on 429 or temporary 5xx errors; no per-client quota is currently configured.

{
  "error": {
    "code": "invalid_parameters",
    "message": "Use distinct vehicle IDs."
  }
}