Documentation

LotShow API

Send a lot photo, get a studio photo back. The API runs the same showroom renderer as the web Studio, on the same credit balance, so a photo uploaded in the Studio and a photo posted from your DMS cost the same.

Base URLhttps://api.lotshow.com/v1

FormatJSON over HTTPS

AccessPro and Elite plans

Everything is a job. You post one photo and a backdrop, we return a job id straight away, and about a minute later the finished image is ready. Register a webhook and we call you; or poll the job. The finished photo also lands in the account's Inventory, grouped under the vehicle you named.

Authentication

Create a key in Settings, under API keys. Keys start with ls_live_ and are shown once, so store it somewhere safe. An account can hold up to 10 live keys, and a key stops working if the account drops to the free plan.

Send the key as a bearer token on every request.

Header

Authorization: Bearer ls_live_••••••••••••••••••••••••••••3f9a

Keys carry the full power of the account. Keep them on your server, never in a browser or an app bundle, and revoke any key you think has leaked from the same Settings page.

Appelez l’API depuis votre serveur. Les navigateurs sont bloqués : l’API n’envoie aucun en-tête CORS, une page web ne peut donc pas l’appeler, et une clé placée dans une page peut être copiée par n’importe qui.

Quickstart

Check the key first. This returns your balance and plan.

cURL

curl https://api.lotshow.com/v1/credits \
  -H "Authorization: Bearer $LOTSHOW_KEY"

200 OK

{
  "balance": 320,
  "plan": "elite",
  "monthly_credits": 1000,
  "renews": "2026-11-13"
}

Then send a photo. One credit is held for the job.

curl https://api.lotshow.com/v1/jobs \
  -H "Authorization: Bearer $LOTSHOW_KEY" \
  -F image=@stock-4471.jpg \
  -F backdrop=grey-concrete \
  -F vehicle="Stock 4471" \
  -F webhook=https://yourdms.com/hooks/lotshow

const form = new FormData();
form.append("image", new Blob([await fs.readFile("stock-4471.jpg")]), "stock-4471.jpg");
form.append("backdrop", "grey-concrete");
form.append("vehicle", "Stock 4471");
form.append("webhook", "https://yourdms.com/hooks/lotshow");

const res = await fetch("https://api.lotshow.com/v1/jobs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LOTSHOW_KEY}` },
  body: form,
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://api.lotshow.com/v1/jobs",
    headers={"Authorization": f"Bearer {os.environ['LOTSHOW_KEY']}"},
    files={"image": open("stock-4471.jpg", "rb")},
    data={
        "backdrop": "grey-concrete",
        "vehicle": "Stock 4471",
        "webhook": "https://yourdms.com/hooks/lotshow",
    },
)
print(res.json())

202 Accepted

{
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "status": "queued",
  "backdrop": "grey-concrete",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "credits_left": 319
}

About a minute later your webhook receives the finished photo. Or fetch the job yourself:

cURL

curl https://api.lotshow.com/v1/jobs/Hn4kR2pXq8VbT1sLw0Za \
  -H "Authorization: Bearer $LOTSHOW_KEY"

When status is completed, output_url is a permanent link to the image. Use it on your listing page.

Photo jobs

A job turns one photo into one studio photo. It moves through four states.

Status	Meaning
`queued`	Accepted and waiting for a renderer. One credit is held.
`processing`	The car is being cut out and placed in the backdrop.
`completed`	Done. `output_url` is set.
`failed`	The photo could not be finished. The credit goes back and `error` says why.

Sending the photo

Post it as a multipart image file, or send JSON with an image_url we download for you. JPEG, PNG and WebP are accepted, up to 15 MB. We straighten and shrink the photo to at most 2048 px before it is rendered, the same as the web Studio does. A photo that isn't the whole car seen from outside fails, and its credit comes back.

Grouping by vehicle

Every job belongs to a vehicle in the account's Inventory. Pass vehicle_id to add to an existing one, or a vin or stock number and we find that vehicle, creating it on first use. A vehicle name works the same way. With none of these, photos go into a vehicle called API. Sending several angles of one car with the same VIN keeps them together.

Vehicles

A vehicle is a car in the account's Inventory with its photos, whether it was made through the API or in the web Studio. Key it by VIN or stock number, the same fields the Studio and the feed export use, and your system never has to store our ids.

Status	Meaning
`empty`	No photos yet.
`processing`	At least one photo is queued or processing.
`completed`	Every photo is finished.
`partial`	Every photo has finished, and at least one failed.

The shot checklist

shots says which of the eight exterior angles the vehicle's photos cover, read from each photo once it is processed: front, front34_left, side_left, rear34_left, rear, rear34_right, side_right and front34_right. A failed photo covers nothing.

Walkaround order

Photos are listed and sent to your feed round the car: front, front right three quarter, right side, rear right three quarter, rear, rear left three quarter, left side, front left three quarter, then any photo without an angle in the order it was sent.

Feed export

With Feed export set up in Settings, POST /v1/vehicles/{id}/feed uploads the finished photos to your listing feed provider over FTP or SFTP, named by VIN or stock number, the same as the Studio's send button.

DMS sync

Your DMS or inventory tool can run the whole flow on its own, keyed by VIN.

Create the vehicle. POST /v1/vehicles with its vin and stock. This step is optional: the first photo sent with a new VIN creates it too.
Post the photos. One POST /v1/jobs per photo with the same vin. Photos sent in parallel land in the one vehicle.
Receive vehicle.completed. Once every photo has finished, the event carries the vehicle and its finished photos in walkaround order.
Use the photos. Download each output_url into your listing, fetch GET /v1/vehicles/{id}/photos, or call POST /v1/vehicles/{id}/feed to push them to your feed provider.

# 1. The vehicle, keyed by its VIN
curl https://api.lotshow.com/v1/vehicles \
  -H "Authorization: Bearer $LOTSHOW_KEY" \
  -H "Idempotency-Key: create-1HGCV1F34PA004471" \
  -H "Content-Type: application/json" \
  -d '{"vin": "1HGCV1F34PA004471", "stock": "4471"}'

# 2. Each photo, sent with the same VIN
for f in lot/4471/*.jpg; do
  curl https://api.lotshow.com/v1/jobs \
    -H "Authorization: Bearer $LOTSHOW_KEY" \
    -H "Idempotency-Key: $(basename "$f")-1HGCV1F34PA004471" \
    -F image=@"$f" \
    -F vin=1HGCV1F34PA004471
done

const api = (path, init = {}) => fetch(`https://api.lotshow.com/v1${path}`, {
  ...init,
  headers: { Authorization: `Bearer ${process.env.LOTSHOW_KEY}`, ...init.headers },
});

// 1. The vehicle, keyed by its VIN
await api("/vehicles", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": "create-1HGCV1F34PA004471" },
  body: JSON.stringify({ vin: "1HGCV1F34PA004471", stock: "4471" }),
});

// 2. Each photo, sent with the same VIN
for (const file of photos) {
  const form = new FormData();
  form.append("image", new Blob([await fs.readFile(file)]), path.basename(file));
  form.append("vin", "1HGCV1F34PA004471");
  await api("/jobs", { method: "POST", headers: { "Idempotency-Key": `${path.basename(file)}-1HGCV1F34PA004471` }, body: form });
}

import os, requests

api = requests.Session()
api.headers["Authorization"] = f"Bearer {os.environ['LOTSHOW_KEY']}"

# 1. The vehicle, keyed by its VIN
api.post(
    "https://api.lotshow.com/v1/vehicles",
    headers={"Idempotency-Key": "create-1HGCV1F34PA004471"},
    json={"vin": "1HGCV1F34PA004471", "stock": "4471"},
)

# 2. Each photo, sent with the same VIN
for path in photos:
    api.post(
        "https://api.lotshow.com/v1/jobs",
        headers={"Idempotency-Key": f"{os.path.basename(path)}-1HGCV1F34PA004471"},
        files={"image": open(path, "rb")},
        data={"vin": "1HGCV1F34PA004471"},
    )

Then, when vehicle.completed arrives, push the photos to the feed:

cURL

curl -X POST https://api.lotshow.com/v1/vehicles/pQ7mT2vK9cLx4RbN1sHd/feed \
  -H "Authorization: Bearer $LOTSHOW_KEY" \
  -H "Idempotency-Key: feed-1HGCV1F34PA004471-1"

200 OK

{
  "ok": true,
  "sent": 8
}

To find a vehicle later from your own records, filter by VIN or stock number: GET /v1/vehicles?vin=1HGCV1F34PA004471.

Backdrops

Il y a 13 décors répartis dans six showrooms : le Hall blanc existe en huit versions de murs et de sol, et les cinq autres showrooms en ont un chacun. La peinture, les finitions et les logos ne sont jamais redessinés ; la voiture est rééclairée selon la pièce et le décor change autour d’elle. Passez le slug dans backdrop. Sans valeur, grey-concrete est utilisé.

Slug	Name
`grey-concrete`	Grey concrete
`white-hall`	White hall
`white-tiles`	White tiles
`micro-cement`	Micro-cement
`stone`	Stone
`plain-stone`	Plain stone
`dealership`	Dealership
`marble-hall`	Marble hall
`photo-booth`	Photo booth
`white-studio`	White studio
`white-hall-plain`	White hall, plain walls
`white-tiles-plain`	White tiles, plain walls
`micro-cement-plain`	Micro-cement, plain walls

Fetch GET /v1/backdrops for a preview image of each.

Webhooks

Webhooks save you polling. There are two ways to receive them, and you can use both.

Per job. Pass a webhook URL when you create the job. Only that job's events go there.
Per account. Register up to 5 endpoints with POST /v1/webhooks and choose the events each one wants.

Events

Event	Sent when
`job.completed`	A studio photo is ready.
`job.failed`	A photo could not be finished. The credit is refunded.
`vehicle.completed`	Every photo of a vehicle has finished and at least one is done. Sent once, and again only after more photos are added. Endpoints only.
`credits.low`	Your balance drops under 20 credits.

Payloads

Each delivery is a JSON POST with the event name, a timestamp, and the fields below.

job.completed

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:42:14.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "grey-concrete",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

job.failed

{
  "event": "job.failed",
  "created_at": "2026-10-14T09:42:02.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "grey-concrete",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "error": "Couldn't finish this photo.",
  "credits_refunded": 1,
  "credits_left": 320
}

vehicle.completed

{
  "event": "vehicle.completed",
  "created_at": "2026-10-14T09:43:10.000Z",
  "vehicle": {
    "id": "pQ7mT2vK9cLx4RbN1sHd",
    "name": "1HGCV1F34PA004471",
    "vin": "1HGCV1F34PA004471",
    "stock": "4471",
    "backdrop": "grey-concrete",
    "photos_total": 8,
    "photos_done": 8,
    "photos_failed": 0,
    "status": "completed",
    "shots": {
      "front": true,
      "front34_left": true,
      "side_left": true,
      "rear34_left": true,
      "rear": true,
      "rear34_right": true,
      "side_right": true,
      "front34_right": true
    },
    "feed": null,
    "created_at": "2026-10-14T09:40:02.000Z",
    "updated_at": "2026-10-14T09:43:10.000Z"
  },
  "photos": [
    {
      "id": "Hn4kR2pXq8VbT1sLw0Za",
      "angle": "front",
      "photo_quality": "good",
      "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…"
    },
    {
      "id": "Tq9cW3nLx7HbR2kPv5Ms",
      "angle": "front34_right",
      "photo_quality": "good",
      "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…"
    }
  ]
}

credits.low

{
  "event": "credits.low",
  "created_at": "2026-10-14T09:50:11.000Z",
  "balance": 18,
  "threshold": 20
}

Verifying a delivery

Every delivery is signed with your account's signing secret (it starts with whsec_ and is in Settings, next to your webhook endpoints). We use the Standard Webhooks scheme, so any library for it works. Three headers come with each request:

Header	Value
`webhook-id`	Unique id of the delivery.
`webhook-timestamp`	Unix time in seconds. Reject anything more than five minutes old.
`webhook-signature`	`v1,` followed by a base64 HMAC-SHA256 of `id.timestamp.body`.

Compute the HMAC over the raw request body, not a re-serialised copy.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, rawBody, headers) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();

  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    const got = Buffer.from(sig ?? "", "base64");
    return version === "v1" && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

import base64, hashlib, hmac, time

def verify(secret: str, raw_body: str, headers: dict) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.{raw_body}".encode()
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for entry in headers["webhook-signature"].split(" "):
        version, _, sig = entry.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

Delivery and retries

Answer with any 2xx within 10 seconds to acknowledge. Anything else counts as a failure and we retry after 1, 5, 15, 60, 180, 360 and 720 minutes, then stop. Recent deliveries and their status codes are listed in Settings.

Credits

The API and the web Studio spend one shared balance. A finished photo costs one credit, whoever asked for it. Credits come from your plan each month and from top-up packs, and both are spendable by the API. See pricing for plans and packs.

A credit is held when a job is accepted. If the job fails, it is returned automatically and credits_charged on the job reads 0. When a request would overdraw the balance it is refused with 402 insufficient_credits.

Jobs

The job object:

Field	Type	Description
`id`	string	Job id.
`status`	string	`queued`, `processing`, `completed` or `failed`.
`backdrop`	string	Backdrop slug.
`vehicle_id`	string	The Inventory vehicle the photo belongs to.
`name`	string	The label you sent, or the file name.
`output_url`	string or null	Permanent link to the finished photo. Set once `completed`.
`photo_quality`	string or null	`good`, `soft` or `poor`: how sharp and clean the car in the photo was.
`angle`	string or null	Which of the eight exterior shots the photo is, such as `front34_left`.
`error`	string or null	Why a job failed.
`credits_charged`	integer	`1`, or `0` when a failed job was refunded.
`seconds`	integer or null	Time from request to finished photo.
`created_at`	string	ISO 8601 time.
`completed_at`	string or null	ISO 8601 time.

Créer une tâche

POST/v1/jobs

Turns one photo into a studio photo. Send a multipart form with an image file, or a JSON body with an image_url. Returns right away; the photo follows by webhook or by polling.

Envoyez un en-tête Idempotency-Key pour réessayer sans risque après un délai dépassé. Pendant 24 heures, une nouvelle tentative avec la même clé et le même corps reçoit la première réponse, marquée Idempotent-Replayed: true, au lieu de créer une deuxième tâche et de dépenser un deuxième crédit.

En-têtes

Idempotency-Keystring: N’importe quelle chaîne unique de 255 caractères maximum, comme un UUID. Facultatif.

Parameters

imagefilerequired: The photo, as a multipart file. JPEG, PNG or WebP, up to 15 MB.
image_urlstring: A public http(s) URL we download instead of an upload. Use it in a JSON body.
backdropstring: A backdrop slug. Defaults to grey-concrete.
vehicle_idstring: An existing vehicle to add the photo to. Wins over everything below.
vinstring: The vehicle's VIN, up to 17 letters and digits without I, O or Q. Finds the vehicle, or creates it named after the VIN. Wins over stock and vehicle.
stockstring: The vehicle's stock number, up to 32 characters. Finds the vehicle, or creates it named after the number. Wins over vehicle.
vehiclestring: A vehicle name, up to 80 characters. Created on first use. Defaults to API.
namestring: A label for the photo, up to 120 characters. Defaults to the file name.
webhookstring: A public https URL that receives this job's events.

202 Accepted

{
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "status": "queued",
  "backdrop": "grey-concrete",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "credits_left": 319
}

Récupérer une tâche

GET/v1/jobs/{id}

Returns one job. A job id from another account answers 404 job_not_found.

200 OK

{
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "status": "completed",
  "backdrop": "grey-concrete",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "photo_quality": "good",
  "angle": "front34_left",
  "error": null,
  "credits_charged": 1,
  "seconds": 62,
  "created_at": "2026-10-14T09:41:12.000Z",
  "completed_at": "2026-10-14T09:42:14.000Z"
}

Lister les tâches

GET/v1/jobs

Jobs created through the API, newest first. Page with starting_after while has_more is true.

Query parameters

limitinteger: Between 1 and 100. Defaults to 20.
starting_afterstring: A job id. Returns the jobs after it.

200 OK

{
  "data": [
    {
      "id": "Hn4kR2pXq8VbT1sLw0Za",
      "status": "completed",
      "backdrop": "grey-concrete",
      "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
      "name": "stock-4471",
      "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
      "photo_quality": "good",
      "angle": "front34_left",
      "error": null,
      "credits_charged": 1,
      "seconds": 62,
      "created_at": "2026-10-14T09:41:12.000Z",
      "completed_at": "2026-10-14T09:42:14.000Z"
    }
  ],
  "has_more": true
}

Vehicles

The vehicle object:

Field	Type	Description
`id`	string	Vehicle id. Jobs carry it as `vehicle_id`.
`name`	string	The name shown in Inventory.
`vin`	string or null	VIN, upper case.
`stock`	string or null	Stock number.
`backdrop`	string or null	The vehicle's backdrop slug.
`photos_total`	integer	Photos on the vehicle.
`photos_done`	integer	Photos completed.
`photos_failed`	integer	Photos that failed.
`status`	string	`empty`, `processing`, `completed` or `partial`.
`shots`	object	Each of the eight exterior angles, `true` when a photo covers it.
`feed`	object or null	The last feed send: `at`, `ok` and `count`.
`created_at`	string	ISO 8601 time.
`updated_at`	string	ISO 8601 time.

Create a vehicle

POST/v1/vehicles

Creates an empty vehicle. Send a JSON body. A VIN or stock number another vehicle of the account already has answers 409 vehicle_exists with that vehicle's vehicle_id.

En-têtes

Idempotency-Keystring: N’importe quelle chaîne unique de 255 caractères maximum, comme un UUID. Facultatif.

Parameters

vinstring: Up to 17 letters and digits without I, O or Q. Stored in upper case.
stockstring: Up to 32 characters.
namestring: Up to 80 characters. Defaults to the VIN, else the stock number.

201 Created

{
  "id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "1HGCV1F34PA004471",
  "vin": "1HGCV1F34PA004471",
  "stock": "4471",
  "backdrop": "grey-concrete",
  "photos_total": 0,
  "photos_done": 0,
  "photos_failed": 0,
  "status": "empty",
  "shots": {
    "front": false,
    "front34_left": false,
    "side_left": false,
    "rear34_left": false,
    "rear": false,
    "rear34_right": false,
    "side_right": false,
    "front34_right": false
  },
  "feed": null,
  "created_at": "2026-10-14T09:40:02.000Z",
  "updated_at": "2026-10-14T09:40:02.000Z"
}

Retrieve a vehicle

GET/v1/vehicles/{id}

Returns one vehicle. A vehicle id from another account answers 404 vehicle_not_found.

200 OK

{
  "id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "1HGCV1F34PA004471",
  "vin": "1HGCV1F34PA004471",
  "stock": "4471",
  "backdrop": "grey-concrete",
  "photos_total": 8,
  "photos_done": 8,
  "photos_failed": 0,
  "status": "completed",
  "shots": {
    "front": true,
    "front34_left": true,
    "side_left": true,
    "rear34_left": true,
    "rear": true,
    "rear34_right": true,
    "side_right": true,
    "front34_right": true
  },
  "feed": {
    "at": "2026-10-14T09:45:30.000Z",
    "ok": true,
    "count": 8
  },
  "created_at": "2026-10-14T09:40:02.000Z",
  "updated_at": "2026-10-14T09:43:10.000Z"
}

List vehicles

GET/v1/vehicles

Every vehicle on the account, newest first, including those made in the web Studio. Page with starting_after while has_more is true.

Query parameters

vinstring: Only the vehicle with this VIN.
stockstring: Only the vehicle with this stock number.
limitinteger: Between 1 and 100. Defaults to 20.
starting_afterstring: A vehicle id. Returns the vehicles after it.

200 OK

{
  "data": [
    {
      "id": "pQ7mT2vK9cLx4RbN1sHd",
      "name": "1HGCV1F34PA004471",
      "vin": "1HGCV1F34PA004471",
      "stock": "4471",
      "backdrop": "grey-concrete",
      "photos_total": 8,
      "photos_done": 8,
      "photos_failed": 0,
      "status": "completed",
      "shots": {
        "front": true,
        "front34_left": true,
        "side_left": true,
        "rear34_left": true,
        "rear": true,
        "rear34_right": true,
        "side_right": true,
        "front34_right": true
      },
      "feed": {
        "at": "2026-10-14T09:45:30.000Z",
        "ok": true,
        "count": 8
      },
      "created_at": "2026-10-14T09:40:02.000Z",
      "updated_at": "2026-10-14T09:43:10.000Z"
    }
  ],
  "has_more": false
}

Update a vehicle

PATCH/v1/vehicles/{id}

Changes the fields you send and leaves the rest. Send null to clear vin or stock. Vehicles are never deleted through the API.

Parameters

namestring: Up to 80 characters.
vinstring or null: Up to 17 letters and digits without I, O or Q.
stockstring or null: Up to 32 characters.

200 OK

{
  "id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "1HGCV1F34PA004471",
  "vin": "1HGCV1F34PA004471",
  "stock": "4471",
  "backdrop": "grey-concrete",
  "photos_total": 8,
  "photos_done": 8,
  "photos_failed": 0,
  "status": "completed",
  "shots": {
    "front": true,
    "front34_left": true,
    "side_left": true,
    "rear34_left": true,
    "rear": true,
    "rear34_right": true,
    "side_right": true,
    "front34_right": true
  },
  "feed": {
    "at": "2026-10-14T09:45:30.000Z",
    "ok": true,
    "count": 8
  },
  "created_at": "2026-10-14T09:40:02.000Z",
  "updated_at": "2026-10-14T09:43:10.000Z"
}

List a vehicle's photos

GET/v1/vehicles/{id}/photos

Every photo of the vehicle as a job object, in walkaround order.

200 OK

{
  "data": [
    {
      "id": "Hn4kR2pXq8VbT1sLw0Za",
      "status": "completed",
      "backdrop": "grey-concrete",
      "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
      "name": "stock-4471",
      "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
      "photo_quality": "good",
      "angle": "front",
      "error": null,
      "credits_charged": 1,
      "seconds": 62,
      "created_at": "2026-10-14T09:41:12.000Z",
      "completed_at": "2026-10-14T09:42:14.000Z"
    },
    {
      "id": "Tq9cW3nLx7HbR2kPv5Ms",
      "status": "completed",
      "backdrop": "grey-concrete",
      "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
      "name": "stock-4471",
      "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
      "photo_quality": "good",
      "angle": "front34_right",
      "error": null,
      "credits_charged": 1,
      "seconds": 62,
      "created_at": "2026-10-14T09:41:12.000Z",
      "completed_at": "2026-10-14T09:42:14.000Z"
    }
  ]
}

Send to your feed

POST/v1/vehicles/{id}/feed

Uploads the vehicle's finished photos to the feed set up in Settings, in walkaround order, named by VIN or stock number. Needs Feed export set up and the VIN or stock number its naming uses. An account can send 30 times an hour. If the server refuses part way, the answer is 502 feed_failed with a reason and how many photos were sent.

En-têtes

Idempotency-Keystring: N’importe quelle chaîne unique de 255 caractères maximum, comme un UUID. Facultatif.

200 OK

{
  "ok": true,
  "sent": 8
}

Backdrops

Lister les décors

GET/v1/backdrops

Les 13 décors, chacun avec une image d’aperçu.

200 OK

{
  "data": [
    {
      "slug": "grey-concrete",
      "name": "Grey concrete",
      "preview_url": "https://lotshow.com/assets/looks/grey.jpg"
    },
    {
      "slug": "white-hall",
      "name": "White hall",
      "preview_url": "https://lotshow.com/assets/looks/original.jpg"
    },
    {
      "slug": "white-tiles",
      "name": "White tiles",
      "preview_url": "https://lotshow.com/assets/looks/tiles.jpg"
    },
    {
      "slug": "micro-cement",
      "name": "Micro-cement",
      "preview_url": "https://lotshow.com/assets/looks/cement.jpg"
    },
    {
      "slug": "stone",
      "name": "Stone",
      "preview_url": "https://lotshow.com/assets/looks/stone.jpg"
    },
    {
      "slug": "plain-stone",
      "name": "Plain stone",
      "preview_url": "https://lotshow.com/assets/looks/stoneflat.jpg"
    },
    {
      "slug": "dealership",
      "name": "Dealership",
      "preview_url": "https://lotshow.com/assets/looks/dealer.jpg"
    },
    {
      "slug": "marble-hall",
      "name": "Marble hall",
      "preview_url": "https://lotshow.com/assets/looks/marble.jpg"
    },
    {
      "slug": "photo-booth",
      "name": "Photo booth",
      "preview_url": "https://lotshow.com/assets/looks/booth.jpg"
    },
    {
      "slug": "white-studio",
      "name": "White studio",
      "preview_url": "https://lotshow.com/assets/looks/studio.jpg"
    },
    {
      "slug": "white-hall-plain",
      "name": "White hall, plain walls",
      "preview_url": "https://lotshow.com/assets/looks/originalflat.jpg"
    },
    {
      "slug": "white-tiles-plain",
      "name": "White tiles, plain walls",
      "preview_url": "https://lotshow.com/assets/looks/tilesflat.jpg"
    },
    {
      "slug": "micro-cement-plain",
      "name": "Micro-cement, plain walls",
      "preview_url": "https://lotshow.com/assets/looks/cementflat.jpg"
    }
  ]
}

Récupérer un décor

GET/v1/backdrops/{slug}

One backdrop. An unknown slug answers 404 backdrop_not_found.

200 OK

{
  "slug": "micro-cement",
  "name": "Micro-cement",
  "preview_url": "https://lotshow.com/assets/looks/cement.jpg"
}

Credits

Récupérer le solde

GET/v1/credits

The shared balance across the web Studio and the API, with the plan it comes from. renews is a date, or null without a monthly plan.

200 OK

{
  "balance": 320,
  "plan": "elite",
  "monthly_credits": 1000,
  "renews": "2026-11-13"
}

Utilisation quotidienne

GET/v1/credits/usage

Photos spent per day, oldest first.

Query parameters

daysinteger: Between 1 and 90. Defaults to 14.

200 OK

{
  "days": [
    {
      "date": "2026-10-13",
      "spent": 35
    },
    {
      "date": "2026-10-14",
      "spent": 29
    }
  ]
}

Vérification de l’état

GET/v1/health

Répond {"ok": true} tant que l’API fonctionne. Aucune clé requise.

200 OK

{
  "ok": true
}

Webhooks

Enregistrer un endpoint

POST/v1/webhooks

Up to 5 endpoints per account. Send a JSON body.

Parameters

urlstringrequired: A public https URL.
eventsstring[]: Any of job.completed, job.failed, vehicle.completed, credits.low. Defaults to the first two.

201 Created

{
  "id": "Wk2pR8sN4vQx1LmT6cZa",
  "url": "https://yourdms.com/hooks/lotshow",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "created_at": "2026-10-14T09:30:05.000Z"
}

Lister les endpoints

GET/v1/webhooks

Every endpoint registered on the account.

200 OK

{
  "data": [
    {
      "id": "Wk2pR8sN4vQx1LmT6cZa",
      "url": "https://yourdms.com/hooks/lotshow",
      "events": [
        "job.completed",
        "job.failed"
      ],
      "created_at": "2026-10-14T09:30:05.000Z"
    }
  ]
}

Envoyer un événement de test

POST/v1/webhooks/{id}/test

Posts a sample event named test to the endpoint and reports how it answered.

200 OK

{
  "delivered": true,
  "status_code": 200,
  "ms": 142
}

Supprimer un endpoint

DELETE/v1/webhooks/{id}

Stops sending events to it.

200 OK

{
  "id": "Wk2pR8sN4vQx1LmT6cZa",
  "deleted": true
}

Errors

Failures use a normal HTTP status and a JSON body with a stable code you can branch on.

402

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. Top up on https://lotshow.com/settings?tab=billing"
  }
}

Status	Code	Meaning
400	`invalid_request`	La requête est mal formée : identifiant, paramètre, corps ou en-tête invalide.
400	`image_required`	Ni fichier `image` ni `image_url` n’a été envoyé.
400	`unknown_backdrop`	`backdrop` ne fait pas partie des 13 slugs.
400	`bad_webhook`	`webhook` doit être une URL https publique.
400	`image_unreachable`	Impossible de télécharger `image_url`.
400	`image_unreadable`	Le fichier n’est pas une photo JPEG, PNG ou WebP.
401	`missing_key`	Pas d’en-tête `Authorization: Bearer`.
401	`invalid_key`	La clé est mal formée, inconnue ou révoquée.
402	`insufficient_credits`	Le solde ne couvre pas la tâche.
403	`plan_required`	Le compte n’est pas en Pro ou Elite.
403	`email_not_verified`	Vérifiez d’abord l’e-mail du compte.
403	`account_blocked`	Le compte ne peut pas lancer de nouvelles tâches.
403	`not_approved`	Le compte n’est pas encore approuvé.
404	`not_found`	Cet endpoint n’existe pas, ou aucun endpoint de webhook n’a cet identifiant.
404	`job_not_found`	Aucune tâche avec cet identifiant sur ce compte.
404	`vehicle_not_found`	Aucun véhicule avec ce `vehicle_id`.
404	`backdrop_not_found`	Aucun décor avec ce slug.
409	`limit_reached`	Le compte a déjà 5 endpoints de webhook.
409	`idempotency_conflict`	L’`Idempotency-Key` a servi avec un autre corps, ou sa première requête est encore en cours.
409	`vehicle_exists`	Another vehicle on the account already has that VIN or stock number. Its id is in `vehicle_id`.
409	`no_photos`	The vehicle has no finished photos to send.
409	`feed_not_configured`	Feed export isn't set up in Settings.
409	`vin_required`	The feed names files by VIN and the vehicle has no 17 character VIN.
409	`stock_required`	The feed names files by stock number and the vehicle has none.
413	`image_too_large`	Les images peuvent peser jusqu’à 15 Mo.
429	`rate_limited`	Trop de requêtes ou de tâches. Ralentissez et réessayez.
429	`feed_limit_reached`	The account has sent to its feed 30 times this hour.
502	`feed_failed`	The feed server refused the connection or the upload. `reason` says why and `sent` how many photos landed.
503	`busy`	Le rendu est en pause un instant. Réessayez sous peu.
500	`internal`	Un problème est survenu de notre côté. Réessayez.

Limits

Limit	Value
Requests per key	120 per minute, bursts up to 120
Live keys per account	10
Webhook endpoints per account	5
Image size	15 MB
Webhook response time	10 seconds
Page size for lists	100
Feed sends per account	30 per hour, 60 photos each

Rate limit headers

Each key has a bucket of 120 tokens that refills at 2 a second. A request spends one token and creating a job spends two, so an idle key can burst and a steady client gets 120 requests a minute. Every answer says where you stand:

Header	Value
`RateLimit-Policy`	`120;w=60;burst=120`
`RateLimit`	`limit=120, remaining=97, reset=12`: tokens left, and seconds until the bucket is full again.
`X-RateLimit-Limit`	`120`
`X-RateLimit-Remaining`	Tokens left.
`X-RateLimit-Reset`	Seconds until the bucket is full again.
`Retry-After`	On a `429` only: seconds to wait before retrying.

Need more throughput? Talk to us.