Prompt pentru agenți AI

# MotorAPIs integration brief

You are integrating the MotorAPIs vehicle data API into my project. Read this whole brief before writing code. Ask me about anything it leaves open instead of guessing.

## Contract
- Base URL: https://motorapis.com/api
- Methods: GET only. The API returns data; it never acts on an auction or a listing.
- Authentication: send the key in the `x-api-key` header on every request. Read it from an environment variable (for example MOTORAPIS_KEY). Never hard-code it, never put it in a URL, never ship it to a browser, never log it.
- Format: JSON in UTF-8. Send `Accept: application/json`.
- Sources: `domain_id` 3 = Copart (auction, USA & Canada), 1 = IAAI (auction, USA & Canada), 12 = Encar (marketplace, South Korea). Without `domain_id` you get every source enabled for the key; a source the key does not include answers 401.
- Data model: one vehicle (VIN, make, model, generation, specs) carries `lots`, one entry per listing on a source, with bids, Buy Now, seller reserve (when the source has one), final bid, damage, title, location, sale date and photos.
- The seller reserve is the seller's minimum, never a sale price. The final bid is the price a lot sold for.
- Missing data: `null` means unknown, never zero or false. Fields can also be absent; read every field defensively.
- Times are ISO 8601 in UTC. Money is a plain number in the source currency (Encar prices are KRW; convert with /exchange-rate-krw-usd).

## Paging
- Lists come in pages: `page` (from 1) and `per_page`. Keep every other filter identical while paging.
- `simple_paginate=1` skips the total count and answers faster. An empty `data` array means you passed the last page.

## Keeping a copy in sync
1. Import once: page through `/cars` and upsert every vehicle by its `id`, and every lot by its lot record id.
2. Every hour: `/cars?minutes=60` returns vehicles changed in the last 60 minutes; upsert them.
3. Every hour: `/archived-lots?minutes=60` returns lots that left the live list (sold or removed); mark them, keeping the final bid.
4. Run one sync at a time (a lock), make each step resumable, and overlap the windows slightly so nothing is missed.

## Errors
- 400: a parameter is not accepted. Fix the request; do not retry.
- 401: the source is not enabled for this key. 403: the key is missing, invalid or inactive. Do not retry either; report it.
- 404: nothing matches.
- 429: too many requests. Wait (respect Retry-After when sent) and retry.
- 5xx and timeouts: retry reads a few times with exponential backoff and jitter, then give up and report.

## Endpoints

### GET /cars
get all cars
Vehicles with active lots from every source enabled for your key, filtered and paged (50 per page by default; use page for the next results). Add minutes to get only recent changes. Each vehicle may contain lots[].seller_reserve. Seller reserve price, when available. Object with price (reserve amount) and updated_at (last reserve update timestamp, or null); seller_reserve is null when no reserve is available. This is not the current bid or a confirmed final sale price. Read it from the relevant lot. Example: {"price":8500,"updated_at":"2026-09-13T10:30:00.000000Z"}.
Parameters:
  - domain_id (query, integer): Source platform ID: 1=IAAI, 3=Copart, 12=Encar. Omit to use sources enabled for the key. Send one integer, not an array. Unsupported IDs return 400; sources outside your access return 401.
  - minutes (query, integer); range 1–4320: this parameter allows you to retrieve only those cars that have been updated in the last few minutes (max 4320 minutes)