> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosnap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Website Inventory
> Retrieve paginated vehicle inventory scraped from a dealership's website.
`POST /v1/inventory/fetch`
Retrieve paginated vehicle inventory for an active dealership. Returns vehicle records with all available fields including pricing, specifications, media, and metadata.
**v1.0 schema lock.** The response shape on this page is the locked v1.0 contract. We will never remove a documented field, never rename a field, and never change a field's type without bumping to v2 (see [Versioning](/get-started/versioning)). New fields may be added additively; your client must tolerate unknown keys. Field nullability and coverage rates are documented in [Concepts: Vehicles — Field coverage SLA](/concepts/vehicles#field-coverage-sla).
## Request Body
Provide either `dealership_url` **or** `dealership_id` (one is required, not both). Both resolve to the same dealership server-side.
| Field | Type | Required | Default | Description |
| ---------------- | ------- | ----------- | ------- | --------------------------------------------------------------------------------------------------- |
| `api_key` | string | Yes | — | Your API key. Accepted in body (canonical) or `?api_key=…` query string. |
| `dealership_url` | string | Conditional | — | The dealership's website URL (e.g. `carlblackroswell.com`). Required if `dealership_id` is omitted. |
| `dealership_id` | string | Conditional | — | Public dealership ID (e.g. `dlr_8cfc0b00a98b`). Required if `dealership_url` is omitted. |
| `page` | integer | No | `1` | Page number for pagination |
| `per_page` | integer | No | `50` | Results per page |
| `condition` | string | No | `all` | Filter by vehicle condition. See values below. |
### Condition Values
| Value | Description |
| ------ | -------------------------------------------------------- |
| `all` | Return both new and used vehicles (default) |
| `new` | Return new vehicles only |
| `used` | Return used vehicles only (includes certified pre-owned) |
## Example
```bash theme={null}
curl -X POST "https://api.autosnap.com/v1/inventory/fetch" \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"dealership_url": "carlblackroswell.com",
"page": 1,
"per_page": 25,
"condition": "new"
}'
```
## Response
```json theme={null}
{
"success": true,
"dealership": {
"name": "Carl Black Buick Gmc",
"website": "carlblackroswell.com",
"street": "11225 Alpharetta Highway",
"city": "Roswell",
"state": "Georgia",
"phone": "678-317-2740"
},
"website_url": "carlblackroswell.com",
"count": 528,
"page": 1,
"per_page": 25,
"total_pages": 22,
"data_age_hours": 1.5,
"vehicles": [
{
"id": "d8a1c0e2-7b42-4f9a-b0e1-5a1f0c2d9b73",
"vin": "1GKS2DKL8TR322035",
"year": 2026,
"make": "GMC",
"model": "Yukon",
"heading": "2026 GMC Yukon Denali",
"stocknum": "TR322035",
"condition": "New",
"certified": false,
"body": "SUV",
"transmission": "10-Speed Automatic",
"series": "Denali",
"door_count": 4,
"odometer": 5,
"engine": "V8 6.2L",
"engine_cyl_count": 8,
"engine_displacement": "6.2",
"fuel": "Gasoline",
"drivetrain_desc": "4WD",
"exterior_color": "Summit White",
"interior_color": "Jet Black",
"base_ext_color": "White",
"base_int_color": "Black",
"msrp": 85485,
"price": 73485,
"internet_price": null,
"list_price": null,
"invoice_price": null,
"book_value": null,
"discount_amount": null,
"final_price": 73933,
"total_discounts": 2250,
"total_fees": 448,
"price_components": {
"components": [
{ "type": "msrp", "label": "MSRP", "amount": 85485, "category": "starting" },
{ "type": "dealer_incentive", "label": "Discount", "amount": 2250, "category": "discount" },
{ "type": "net_price_with_dealer_fees", "label": "Final Price", "amount": 73933, "category": "final" },
{ "type": "dealer_fee", "label": "Doc Fee", "amount": 448, "category": "fee" }
],
"total_fees": 448,
"final_price": 73933,
"starting_price": 85485,
"total_discounts": 2250
},
"vdp_link": "https://www.carlblackroswell.com/inventory/...",
"photo_url_list": [
{ "url": "https://vehicle-images.carscommerce.inc/...", "index": 0 }
],
"features": ["AWD", "Leather", "Navigation", "Sunroof"],
"description": "...",
"age_days": 25,
"in_transit": false,
"dealership_active": true,
"first_seen_at": "2026-03-15T00:00:00Z",
"scraped_date": "2026-04-09",
"created_at": "2026-03-15T00:00:00Z",
"updated_at": "2026-04-09T16:38:02Z",
"last_seen": "2026-04-09T16:38:02Z",
"city_mpg": 14,
"hwy_mpg": 19,
"inventory_date": "2026-04-09"
}
]
}
```
`price_components` and `photo_url_list` are returned as native JSON objects/arrays. See [Concepts: Vehicles](/concepts/vehicles) for field details and [Provider Coverage: Price Breakdown](/concepts/provider-coverage#price-breakdown-coverage) for the full component schema.
**Zero-to-null conversion:** Fields with a value of `0` are returned as `null` to indicate missing data. This applies to all price fields (`msrp`, `price`, `internet_price`, `list_price`, `invoice_price`, `book_value`, `discount_amount`, `final_price`, `total_discounts`, `total_fees`), fuel economy (`city_mpg`, `hwy_mpg`), `age_days`, and `engine_cyl_count`.
**Color fields:** In addition to the raw `exterior_color` and `interior_color` fields, each vehicle includes `base_ext_color` and `base_int_color` -- normalized base color values (e.g., "Black", "White", "Silver") standardized across all providers.
**Photo URL substitution:** When rehosted images are available, `photo_url_list` contains CDN-hosted URLs instead of the original dealer website URLs. The original URLs are not returned in this case.
**Per-dealer scope.** The response reflects a single dealership's public inventory. The same VIN may appear at other dealerships you have access to — most commonly when a dealer group shares used-inventory across multiple rooftop websites. See [Concepts: Vehicles — Core identifiers](/concepts/vehicles#core-identifiers) for how to handle cross-dealer uniqueness.
**Data freshness.** `data_age_hours` (top-level, `number | null`) reports the number of hours since the most recent scrape pass observed any vehicle in this dealership's active inventory, rounded to one decimal. Equivalent to `now - max(vehicle.last_seen)` across the whole dealership — it does **not** vary by `page`, `per_page`, or `condition` filter (whole-dealership scope, not page scope). Lower is fresher. Most dealers are scraped on a 6-hour cadence, with some on 12-hour, so a typical value is `0.5` to `12.0`. Values that significantly exceed the dealer's expected cadence indicate a delayed or failing scrape — consider a more conservative price-display strategy in that case. Returns `null` when the dealership has no active vehicles.
## Errors
| Status | Detail | Condition |
| ------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `404` | `"Dealership not found. Use POST /v1/dealers/resolve first."` | The `dealership_url` is not in the system. Resolve and set up the dealer first. |
## OpenAPI
````yaml POST /v1/inventory/fetch
openapi: 3.0.3
info:
title: AutosnapAI Origin API
description: Dealer resolution, inventory management, and webhook APIs
version: 1.0.0
servers:
- url: https://api.autosnap.com
description: Production
security: []
paths:
/v1/inventory/fetch:
post:
tags:
- origin
summary: Fetch Website Inventory
description: |-
Fetch paginated vehicle inventory for a known dealership URL.
Dealership must already be resolved and in the system.
operationId: fetch_inventory_v1_inventory_fetch_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FetchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
FetchRequest:
properties:
api_key:
type: string
title: Api Key
dealership_url:
type: string
title: Dealership Url
page:
type: integer
nullable: true
title: Page
default: 1
per_page:
type: integer
nullable: true
title: Per Page
default: 50
condition:
type: string
nullable: true
title: Condition
type: object
required:
- api_key
- dealership_url
title: FetchRequest
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
````