{"openapi":"3.1.0","info":{"title":"Swiftly Cars API","version":"0.1.0","description":"Read-only inventory and express prices for NEW Audi vehicles (Los Angeles / Orange County), plus sourcing-description parsing. Money is integer US cents. Express prices are fixed offers for the listed VIN while it is listed, available only through Swiftly Cars (MSRP less one monthly express discount; status \"unavailable\" means contact us); they exclude tax, registration and dealer fees. To go ahead, hand off to the buyer with a link to /inventory/{vin} or /?q={question}; the buyer gives their own contact details and consent on the site. The website chat endpoints are not part of this API."},"servers":[{"url":"https://swiftlycars.com"}],"paths":{"/api/v1/health":{"get":{"summary":"Inventory snapshot freshness, coverage and integration states","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/inventory":{"get":{"summary":"List NEW vehicles in the accepted snapshot","parameters":[{"name":"modelId","in":"query","description":"Exact source model id, e.g. q8, sq8, rs-q8-suv-performance (separate models). Valid ids are listed in facets.models. Overrides family.","schema":{"type":"string","example":"q8"}},{"name":"q","in":"query","description":"VIN, stock number or keywords (all words must match).","schema":{"type":"string","maxLength":60}},{"name":"trim","in":"query","description":"Trim value from facets.trim (not-listed = source did not publish one).","schema":{"type":"string","example":"premium-plus"}},{"name":"ext","in":"query","description":"Exterior base color value from facets.ext.","schema":{"type":"string","example":"black"}},{"name":"int","in":"query","description":"Interior base color value from facets.int.","schema":{"type":"string","example":"beige"}},{"name":"status","in":"query","description":"Source listing status value from facets.status (dealer-stock, port-stock, intransit-from-factory, not-published). A source label, not confirmed availability.","schema":{"type":"string"}},{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"priceMin","in":"query","description":"Minimum price (your price, after any Audi Customer Credit) in whole US dollars. Vehicles without a preview price are excluded when a range is set.","schema":{"type":"integer","minimum":0}},{"name":"priceMax","in":"query","description":"Maximum price (your price, after any Audi Customer Credit) in whole US dollars.","schema":{"type":"integer","minimum":0}},{"name":"sort","in":"query","description":"Default is listing order. Unknown prices sort last; ties break on VIN. Applied to the full result before pagination.","schema":{"type":"string","enum":["price-asc","price-desc","year-desc","model-az"]}},{"name":"family","in":"query","description":"Legacy model-family grouping (q8 = Q8 + SQ8 + RS Q8). Ignored when modelId is set.","schema":{"type":"string","example":"q5"}},{"name":"model","in":"query","description":"Legacy loose model-name match (ignores body words such as Sportback). Prefer modelId.","schema":{"type":"string","example":"SQ5"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Page of vehicles. Also returns query (the applied filters), facets (models with id/name/family/count; trim/ext/int/status/year with value/label/count, each counted under the other active filters) and items[].modelId.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid query (invalid_query), e.g. unknown modelId/trim/sort or priceMin above priceMax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inventory/{vin}":{"get":{"summary":"Vehicle detail with express price preview (or Contact us) and source provenance","parameters":[{"name":"vin","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-HJ-NPR-Z0-9]{17}$"}}],"responses":{"200":{"description":"Vehicle","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid VIN"},"404":{"description":"Not in snapshot"},"410":{"description":"No longer listed"}}}},"/api/v1/models":{"get":{"summary":"Model families in the snapshot with counts and MSRP ranges","responses":{"200":{"description":"Families","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/models/{slug}":{"get":{"summary":"One model family with its vehicles","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Family","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown family"}}}},"/api/v1/specials":{"get":{"summary":"The partner dealership's current lease and finance specials: published terms, fine print word for word, expiry, plus computed figures (each lease's total: the amount due at signing plus the monthly payments; finance cost per $10,000). Lease figures are before tax and DMV fees (tax, title and registration), which the amount due at signing does not include. Expired offers are left out.","responses":{"200":{"description":"Specials","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/pricing/rules":{"get":{"summary":"Pricing rule set currently used for previews","responses":{"200":{"description":"Rule set","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/price-preview":{"post":{"summary":"Price preview for a VIN in the snapshot","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vin"],"properties":{"vin":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Preview or unavailable reason","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid"},"404":{"description":"Not in snapshot"}}}},"/api/v1/sourcing/parse":{"post":{"summary":"Turn a description into a structured sourcing spec, targeted questions and inventory matches","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":1000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Spec, questions, matches","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/sourcing-requests":{"post":{"summary":"Create a sourcing request for a signed-in customer (Bearer token) with explicit consent; without a durable store it returns an unsaved dry-run preview. Agents cannot sign in for a buyer: hand off instead.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["spec","consent"],"properties":{"spec":{"type":"object"},"consent":{"const":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Dry-run preview (persisted: false) or existing request","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid"},"401":{"description":"Sign-in required"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}