> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Vehicles API Overview

> Complete vehicle inventory management, inspection tracking, and damage reporting

## Introduction

The Vehicles API provides comprehensive endpoints for managing your vehicle inventory throughout the entire vehicle lifecycle - from initial listing to final sale. This includes vehicle data management, damage tracking, inspection coordination, and status updates.

## Key Features

<CardGroup cols={2}>
  <Card title="Inventory Management" icon="car">
    Create, update, search, and filter your vehicle inventory with advanced search capabilities
  </Card>

  <Card title="Damage Tracking" icon="triangle-exclamation">
    Record and manage damage assessments with detailed reporting and cost estimation
  </Card>

  <Card title="Inspection Integration" icon="magnifying-glass">
    Connect with AI-powered inspection services for automated damage detection
  </Card>

  <Card title="Status Workflow" icon="arrows-spin">
    Track vehicles through statuses: LOADING, INSPECTED, SOLD with full history
  </Card>
</CardGroup>

## Vehicle Lifecycle

```mermaid theme={null}
graph LR
    A[Create Vehicle] --> B[LOADING]
    B --> C[Add Images & Details]
    C --> D[Inspection]
    D --> E[INSPECTED]
    E --> F[Publish Listing]
    F --> G[SOLD]

    style A fill:#282F75
    style E fill:#4360B1
    style G fill:#28a745
```

## API Endpoints

### Vehicle Management

| Endpoint         | Method | Description                                   |
| ---------------- | ------ | --------------------------------------------- |
| `/vehicles`      | GET    | List all vehicles with filters and pagination |
| `/vehicles/{id}` | GET    | Get vehicle details by ID                     |
| `/vehicles`      | POST   | Create a new vehicle                          |
| `/vehicles/{id}` | PATCH  | Update vehicle information                    |
| `/vehicles/{id}` | DELETE | Delete a vehicle                              |

### Search & Filter

| Endpoint                        | Method | Description                      |
| ------------------------------- | ------ | -------------------------------- |
| `/vehicles/public`              | GET    | Get published public vehicles    |
| `/vehicles/status/{status}`     | GET    | Filter by purchase status        |
| `/vehicles/make/{make}`         | GET    | Filter by vehicle make           |
| `/vehicles/location/{location}` | GET    | Filter by location               |
| `/vehicles/search/{q}`          | GET    | Full-text search across vehicles |

### Damage Management

| Endpoint                            | Method | Description                                      |
| ----------------------------------- | ------ | ------------------------------------------------ |
| `/vehicles/{id}/complete`           | PUT    | Complete vehicle data with damages and analytics |
| `/vehicles/{id}/damages`            | POST   | Add damage record to vehicle                     |
| `/vehicles/{id}/damages/{damageId}` | DELETE | Remove damage record                             |
| `/vehicles/{id}/estimate-damages`   | POST   | Trigger AI damage estimation                     |

### Inspection Workflow

| Endpoint                          | Method | Description                         |
| --------------------------------- | ------ | ----------------------------------- |
| `/vehicles/phase/preprocess/{id}` | POST   | Attach preprocessing job to vehicle |
| `/vehicles/webhooks/ml-results`   | POST   | Webhook for ML processing results   |

## Vehicle Object Schema

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user_uuid",
  "make": "Honda",
  "model": "Civic",
  "overviewYear": 2021,
  "price": 25000,
  "km": 45000,
  "location": "Casablanca, Morocco",
  "seat": 5,
  "gearBox": "Automatic",
  "fuel": "Gasoline",
  "engineDisplacement": 1800,
  "numberCV": 140,
  "averageConsumption": "6.5L/100km",
  "outside": "Excellent",
  "inside": "Good",
  "ownerNumber": 1,
  "purchaseStatus": "INSPECTED",
  "archive": false,
  "published": true,
  "adNumber": 12345,
  "immatricule": "ABC-1234",
  "overviewImgs": "https://...",
  "postedBy": "Dealer XYZ",
  "functionalities": "GPS, Bluetooth, Cruise Control",
  "feature": "Sunroof, Leather Seats",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

## Query Parameters

### Filtering Options

All list endpoints support the following filters:

* `search` - Global search across make, model, location
* `make` - Filter by vehicle make
* `model` - Filter by vehicle model
* `minPrice` / `maxPrice` - Price range filter
* `minYear` / `maxYear` - Year range filter
* `minKm` / `maxKm` - Mileage range filter
* `fuel` - Filter by fuel type
* `gearBox` - Filter by transmission type
* `location` - Filter by location
* `purchaseStatus` - Filter by status (LOADING, INSPECTED, SOLD)
* `published` - Filter by publication status
* `archive` - Filter by archive status

### Pagination & Sorting

* `page` - Page number (default: 1)
* `limit` - Items per page (default: 10, max: 100)
* `sortBy` - Sort field (price, overviewYear, km, createdAt)
* `sortOrder` - Sort direction (asc, desc)

## Purchase Status Workflow

### Status Transitions

<Steps>
  <Step title="LOADING">
    Vehicle is being added to inventory. Images and details are being collected.
  </Step>

  <Step title="INSPECTED">
    Vehicle has been inspected. Damage reports and condition assessments are complete.
  </Step>

  <Step title="SOLD">
    Vehicle has been sold. Transaction complete.
  </Step>
</Steps>

## Damage Object Schema

```json theme={null}
{
  "id": "damage_uuid",
  "type": "Dent",
  "severity": "moderate",
  "location": "Front Right Door",
  "description": "Small dent approximately 5cm diameter",
  "estimatedCost": 350,
  "imageUrls": [
    "https://...",
    "https://..."
  ]
}
```

### Severity Levels

* `minor` - Cosmetic damage, minimal repair needed
* `moderate` - Visible damage requiring professional repair
* `severe` - Structural damage requiring significant work

## Rate Limits

Vehicle API endpoints follow the standard rate limits:

| Plan         | Requests/Hour | Burst Limit |
| ------------ | ------------- | ----------- |
| Free         | 1,000         | 50          |
| Starter      | 10,000        | 200         |
| Professional | 100,000       | 1,000       |
| Enterprise   | Unlimited     | Custom      |

## Error Codes

| Code                          | Description                    |
| ----------------------------- | ------------------------------ |
| `VEHICLE_NOT_FOUND`           | Vehicle ID does not exist      |
| `VEHICLE_ALREADY_SOLD`        | Cannot modify sold vehicles    |
| `UNAUTHORIZED_VEHICLE_ACCESS` | User does not own this vehicle |
| `INVALID_PURCHASE_STATUS`     | Invalid status transition      |
| `DUPLICATE_IMMATRICULE`       | License plate already exists   |

## Best Practices

<AccordionGroup>
  <Accordion title="Always validate vehicle data before creation">
    Ensure all required fields are provided and valid. Use the schema validation to prevent errors.
  </Accordion>

  <Accordion title="Use pagination for large inventories">
    For inventories with 1000+ vehicles, always use pagination with reasonable page sizes (10-50).
  </Accordion>

  <Accordion title="Leverage caching for public listings">
    Public vehicle listings are cached for 5 minutes. Use this to optimize performance.
  </Accordion>

  <Accordion title="Track status transitions">
    Maintain audit logs of status changes for compliance and business intelligence.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="List Vehicles" icon="list" href="/api-reference/vehicles/list">
    Learn how to retrieve and filter your vehicle inventory
  </Card>

  <Card title="Create Vehicle" icon="plus" href="/api-reference/vehicles/create">
    Add new vehicles to your inventory
  </Card>

  <Card title="Damage Management" icon="wrench" href="/api-reference/vehicles/damages">
    Manage damage reports and estimates
  </Card>

  <Card title="Search & Filter" icon="filter" href="/api-reference/vehicles/search">
    Advanced search and filtering options
  </Card>
</CardGroup>