Skip to main content
inventory:read The inventory:read scope provides read-only access to your dealership’s vehicle inventory data. This includes listing vehicles, viewing individual vehicle details, retrieving AI-generated descriptions, downloading inventory feeds (JSON or XML), and checking inventory statistics.

​
Endpoints

MethodPathDescription
GET/public/inventoryList vehicles
GET/public/inventory/{vin}Get vehicle details
GET/public/inventory/{vin}/descriptionGet AI description
GET/public/inventory/feedGet inventory feed
GET/public/inventory/statsGet inventory stats

​
List vehicles

GET /public/inventory
Returns a paginated list of vehicles in your inventory.

​
Query parameters

NameTypeDefaultDescription
limitinteger25Number of results to return (1-100)
cursorstring—Base64-encoded cursor from a previous response
makestring—Filter by make (case-insensitive partial match)
modelstring—Filter by model (case-insensitive partial match)
yearinteger—Filter by exact model year
conditionstring—Filter by condition: new or used

​
Example

curl "https://api.app.hrizn.io/v1/public/inventory?limit=10&make=Honda&condition=new" \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK

{
  "data": [
    {
      "vin": "1HGBH41JXMN109186",
      "year": 2026,
      "make": "Honda",
      "model": "Civic",
      "trim": "EX",
      "condition": "new",
      "price": 28500,
      "mileage": 12,
      "exterior_color": "Crystal Black Pearl",
      "interior_color": "Black",
      "has_description": true,
      "image_url": "https://cdn.example.com/vehicles/1HGBH41JXMN109186/main.jpg",
      "updated_at": "2026-02-01T10:00:00Z"
    },
    {
      "vin": "1HGBH41JXMN109187",
      "year": 2026,
      "make": "Honda",
      "model": "Accord",
      "trim": "Sport",
      "condition": "new",
      "price": 32900,
      "mileage": 8,
      "exterior_color": "Lunar Silver Metallic",
      "interior_color": "Gray",
      "has_description": false,
      "image_url": "https://cdn.example.com/vehicles/1HGBH41JXMN109187/main.jpg",
      "updated_at": "2026-02-01T09:30:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJ2aW4iOiIxSEdCSDQxSlhNTjEwOTE4NyJ9",
    "total_count": 156
  }
}

​
Status codes

CodeDescription
200Success
401Missing or invalid API key
403API key does not have inventory:read scope
500Internal server error

​
Get vehicle details

GET /public/inventory/{vin}
Returns full details for a single vehicle including all available fields.

​
Path parameters

NameTypeRequiredDescription
vinstringYesVehicle Identification Number

​
Example

curl https://api.app.hrizn.io/v1/public/inventory/1HGBH41JXMN109186 \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK

{
  "data": {
    "vin": "1HGBH41JXMN109186",
    "year": 2026,
    "make": "Honda",
    "model": "Civic",
    "trim": "EX",
    "condition": "new",
    "price": 28500,
    "msrp": 29500,
    "mileage": 12,
    "exterior_color": "Crystal Black Pearl",
    "interior_color": "Black",
    "engine": "2.0L 4-Cylinder",
    "transmission": "CVT",
    "drivetrain": "FWD",
    "fuel_type": "Gasoline",
    "body_style": "Sedan",
    "features": [
      "Apple CarPlay",
      "Android Auto",
      "Honda Sensing",
      "Sunroof",
      "Heated Seats"
    ],
    "image_url": "https://cdn.example.com/vehicles/1HGBH41JXMN109186/main.jpg",
    "images": [
      "https://cdn.example.com/vehicles/1HGBH41JXMN109186/main.jpg",
      "https://cdn.example.com/vehicles/1HGBH41JXMN109186/interior.jpg",
      "https://cdn.example.com/vehicles/1HGBH41JXMN109186/rear.jpg"
    ],
    "ai_description": "The 2026 Honda Civic EX offers a perfect blend of style, technology, and efficiency...",
    "description_status": "completed",
    "created_at": "2026-01-15T08:00:00Z",
    "updated_at": "2026-02-01T10:00:00Z"
  }
}

​
Status codes

CodeDescription
200Success
400VIN is required
401Missing or invalid API key
403API key does not have inventory:read scope
404Vehicle not found or belongs to a different site
500Internal server error

​
Get AI description

GET /public/inventory/{vin}/description
Returns the AI-generated description for a vehicle. If no description has been generated yet, the status will be not_generated.

​
Path parameters

NameTypeRequiredDescription
vinstringYesVehicle Identification Number

​
Example

curl https://api.app.hrizn.io/v1/public/inventory/1HGBH41JXMN109186/description \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK (description available)

{
  "data": {
    "vin": "1HGBH41JXMN109186",
    "status": "completed",
    "description": "The 2026 Honda Civic EX offers a perfect blend of style, technology, and efficiency. With its turbocharged engine, advanced Honda Sensing suite, and premium interior amenities, this sedan delivers an exceptional driving experience at a competitive price point.",
    "generated_at": "2026-02-01T09:45:00Z"
  }
}

​
Response — 200 OK (not generated)

{
  "data": {
    "vin": "1HGBH41JXMN109186",
    "status": "not_generated",
    "description": null,
    "generated_at": null
  }
}

​
Status codes

CodeDescription
200Success
400VIN is required
401Missing or invalid API key
403API key does not have inventory:read scope
404Vehicle not found or belongs to a different site
500Internal server error

​
Get inventory feed

GET /public/inventory/feed
Returns the complete inventory feed. Supports both JSON and XML formats.

​
Query parameters

NameTypeDefaultDescription
formatstringjsonResponse format: json or xml

​
Example — JSON feed

curl "https://api.app.hrizn.io/v1/public/inventory/feed?format=json" \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK (JSON)

{
  "data": {
    "count": 156,
    "vehicles": [
      {
        "vin": "1HGBH41JXMN109186",
        "year": 2026,
        "make": "Honda",
        "model": "Civic",
        "trim": "EX",
        "condition": "new",
        "price": 28500,
        "mileage": 12,
        "exterior_color": "Crystal Black Pearl",
        "interior_color": "Black",
        "ai_description": "The 2026 Honda Civic EX offers a perfect blend of style...",
        "image_url": "https://cdn.example.com/vehicles/1HGBH41JXMN109186/main.jpg"
      }
    ]
  }
}

​
Example — XML feed

curl "https://api.app.hrizn.io/v1/public/inventory/feed?format=xml" \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK (XML)

Returns Content-Type: application/xml: 
<?xml version="1.0" encoding="UTF-8"?>
<inventory count="156">
  <vehicle>
    <vin>1HGBH41JXMN109186</vin>
    <year>2026</year>
    <make>Honda</make>
    <model>Civic</model>
    <trim>EX</trim>
    <condition>new</condition>
    <price>28500</price>
    <mileage>12</mileage>
    <exterior_color>Crystal Black Pearl</exterior_color>
    <interior_color>Black</interior_color>
    <ai_description>The 2026 Honda Civic EX offers a perfect blend of style...</ai_description>
    <image_url>https://cdn.example.com/vehicles/1HGBH41JXMN109186/main.jpg</image_url>
  </vehicle>
</inventory>

​
Status codes

CodeDescription
200Success
401Missing or invalid API key
403API key does not have inventory:read scope
500Internal server error

​
Get inventory stats

GET /public/inventory/stats
Returns summary statistics for your inventory.

​
Example

curl https://api.app.hrizn.io/v1/public/inventory/stats \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK

{
  "data": {
    "total_vehicles": 156,
    "with_ai_description": 142,
    "without_ai_description": 14,
    "new_vehicles": 89,
    "used_vehicles": 67,
    "description_coverage_pct": 91
  }
}

​
Status codes

CodeDescription
200Success
401Missing or invalid API key
403API key does not have inventory:read scope
500Internal server error

​
Error response — Missing scope

If your API key does not include inventory:read, any request to these endpoints returns: 
{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: inventory:read",
    "details": {
      "required_scopes": ["inventory:read"]
    }
  }
}
Last modified on March 1, 2026