OmniaAuto API

{
  "openapi": "3.0.3",
  "info": {
    "title": "OmniaAuto — Canadian Vehicle Listings API",
    "version": "1.0.0",
    "description": "Live Canadian Market vehicle listings, VIN lookup, valuation and market statistics\n\n**Response schema:** every listing surface (listings, vin, feed, downloads) returns one fixed column set: vin, MY, Make, model, Trim, Condition, Demo, Certified, mileage, price, InitialPrice, DaysOnMarket, exterior_color, interior_color, body_type, doors, passengers, Size Class, Powertrain, drivetrain, Engine_size, transmission, fuel_type, Seller Name, Address, City, Province, PostalCode, Country, Latitude, Longitude, Is_Cross_Listed, Phone. Demo, Certified and Is_Cross_Listed are Yes/No; price and InitialPrice are whole dollar amounts (no cents); InitialPrice is the first price observed for the listing and DaysOnMarket is how many whole days it has been live. Colours/body style are always English; Condition is New/Used (Demo & Certified count as Used).\n\n**Agent-native:** the same data is available as a hosted MCP server at `https://mcp.omniaauto.ca/mcp` (Authorization: Bearer <API key>) — connect it straight into Claude, ChatGPT, or any MCP client. An MCP tool call returns at most **20 listings** (10 on the Personal and Pro plans), and every plan carries a monthly ceiling on how many distinct vehicles it may disclose over MCP. Two MCP-only plans are sold direct, both flat monthly subscriptions (cancel anytime) with three **independent** monthly allowances, each a hard stop with no overage: **Personal** — CA$19.99/month: 100 car listings, 100 price checks and 1,000 market questions — and **Pro** — CA$49/month: 300 car listings, 500 price checks and 5,000 market questions. *Car listings* = distinct vehicles shown by `search_listings` / `get_vin` (a vehicle already shown this month does not count again); *price checks* = `valuation` calls; *market questions* = every other tool call (search and VIN lookups count one each, as well as using car listings for new vehicles). Running out of one allowance leaves the other two working: the tool returns `allowance_exhausted` with a note naming which allowance ran out and what still works.\n\n**Statistics cover all of Canada on every MCP plan.** Counts, averages, medians, distributions, breakdowns, and valuations may scan any slice up to and including the entire dataset — prices, trends, and supply across all of Canada — and never use the car-listings allowance, because a statistic discloses no individual vehicle (each call is still one market question or one price check). The per-call listing cap and the monthly distinct-vehicle ceiling apply **only to row-level records actually returned**: a result count (\"39,842 vehicles match\") is not a disclosure and is always exact. The billed unit is the distinct **vehicle**, not the VIN string — row-level detail describing one vehicle counts as one vehicle disclosed whether or not the VIN field is present in the response, and two listings of the same vehicle at different sellers count once.\n\n**Errors** follow RFC 9457 (`application/problem+json`): `type`, `title`, `status`, plus the `error` code you branch on and a human `detail`.\n\n**What one call costs.** A call is a request returning up to **25 records**. A larger page counts proportionally — a 100-record page is 4 calls, a 500-record page is 20 — because the plan is sized around records returned, not requests made. A request returning no record set (a decode, a market summary, a lookup that finds nothing) is always exactly one call.\n\n**Quota headers** on every authenticated response: `X-RateLimit-*` for the per-second bucket, `X-Quota-Limit`/`-Remaining`/`-Reset` for the monthly call allowance with `X-Quota-Policy` saying whether passing it is a hard stop (plans that publish a fixed monthly call allowance and carry no overage) or bills as overage (every other plan), and `X-Record-Limit`/`-Remaining` for the monthly record allowance (`X-Record-Cost` is the records-per-call divisor). Past the record allowance we do not cut you off: your page size drops to 5 records per call for the rest of the month (`X-Record-Policy: page-limited`), so search keeps working while bulk export does not. Past **twice** the record allowance, row-returning endpoints refuse with **402** `record_cap_exhausted` until the 1st — aggregates and VIN lookups still work. `/v1/feed` and the uncapped Feed and Enterprise tiers are exempt from both. Continuous full-dataset access is what a Feed plan licenses. `GET /v1/usage` returns both allowances.\n\n**Conditional requests.** Every response on the data endpoints carries an `ETag`. Send it back as `If-None-Match` and an unchanged answer returns **304 Not Modified** with no body — and, because the validator is derived from the serving-layer version rather than from hashing a response we would have had to build anyway, the query never runs. **A 304 does not count against your quota.** Pair it with `listed_since` and a poller costs almost nothing on either side.\n\n**REST counts listings; MCP counts vehicles.** The same corpus is served two ways ON PURPOSE, and the two surfaces will report different totals for the identical filter. REST is a LISTING API: `/v1/listings`, `/v1/feed`, `/v1/market` and `/v1/health` return and count every listing instance, so a vehicle a seller group has posted at six of its locations is six rows and counts six times — that is what a developer building their own UI needs, since each instance has its own seller, price and URL. The hosted MCP server is a VEHICLE API: `search_listings`, `market_stats` and `coverage` return and count one row per physical vehicle (per VIN), cross-listings already collapsed. Across the live corpus that is 856,200 listings versus 618,078 vehicles — about 28% — and inside a single city it is typically 11–15%. Neither number is wrong and neither is a bug: an LLM reasons over rows and would otherwise report the same car repeatedly as separate options and double-count every summary, while a REST client that wants one row per vehicle can deduplicate on `vin` itself. MCP responses carry `\"unit\": \"vehicle\"`, and `coverage` returns the listing count alongside the vehicle count so the two can be reconciled.\n\n**Agent-native:** the same data is available as a hosted MCP server at `https://mcp.omniaauto.ca/mcp` (Authorization: Bearer <API key>) — connect it straight into Claude, ChatGPT, or any MCP client.\n",
    "contact": {
      "name": "OmniaAuto",
      "url": "https://omniaauto.ca/contact",
      "email": "support@omniaauto.ca"
    }
  },
  "servers": [
    {
      "url": "https://api.omniaauto.ca",
      "description": "production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {}
}