Retrieve a vehicle

Fetch processed media for a vehicle using the dealerVinId from Transform a vehicle. Poll until every requested asset is done, or receive the same payload on your webhook.

Retrieves the processed media and metadata for a vehicle by any one of its identifiers.

Fields with no value are omitted from the response rather than returned as null, so do not rely on a key being present.

GEThttps://api.spyne.ai/api/pv1/merchandise

AuthBearer tokenSame shape asWebhook payload

Prefer ReadMe's own explorer? Open it here.

Before you call it

Query parameters

Parameter	Type	Required	Description
`dealerVinId`	string	Optional	Spyne's record identifier, returned by the processing request. When supplied, the other identifiers are ignored.
`vin`	string	Optional	The vehicle's 17-character alphanumeric VIN.
`stockNumber`	string	Optional	The dealer's internal inventory identifier.
`registrationNumber`	string	Optional	The vehicle's official registration number.
`teamId`	string	Optional	Team the lookup is scoped to. If omitted, the team from the authenticated API credential is used. "Note": a supplied teamId takes precedence over the credential's team.

Sample request

curl --request GET \
  --url 'https://api.spyne.ai/api/pv1/merchandise' \
  --header 'Authorization: Bearer YOUR_API_KEY'

import requests

url = "https://api.spyne.ai/api/pv1/merchandise"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.status_code, response.json())

const response = await fetch("https://api.spyne.ai/api/pv1/merchandise", {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
console.log(response.status, await response.json());

Sample response

{
  "vin": "1HGCM82633A004352",
  "stockNumber": "STK-4471",
  "dealerVinID": "3bd1c257-9b32-4933-8cf4-a445fd5b37b8",
  "source": "API",
  "dealerId": "86fc402add",
  "clientMetaData": {
    "dmsRef": "RO-88213"
  },
  "mediaData": {
    "image": {
      "skuId": "sku_9f2c",
      "aiStatus": "COMPLETED",
      "qcStatus": "APPROVED",
      "imageData": [
        {
          "angle": "front",
          "status": "Done",
          "frameNo": 1,
          "imageId": "img-bbef1ea1",
          "imageName": "0c4fb0ff",
          "inputImage": "https://cdn.example.com/veh/front.jpg",
          "outputImage": "https://cdn.example.com/veh/front-processed.jpg",
          "backgroundId": "13488",
          "category": "Exterior",
          "clientMetaData": {
            "position": "front"
          }
        }
      ]
    },
    "spin": {
      "skuId": "sku_7a11",
      "aiStatus": "COMPLETED",
      "qcStatus": "APPROVED",
      "spinIframe": "https://spin.spyne.ai/embed/abc123",
      "thumbnailUrl": "https://cdn.example.com/spin-thumb.jpg"
    },
    "video": {
      "aiStatus": "COMPLETED",
      "qcStatus": "APPROVED",
      "videoId": "vid_5512",
      "videoUrl": "https://cdn.example.com/feature.mp4"
    }
  }
}

{
  "message": "At least one identifier (dealerVinId, vin, stockNumber, or registrationNumber) is required"
}

{
  "message": "auth_key is required"
}

{
  "status": "401",
  "message": "Invalid Auth key"
}

{
  "message": "Inventory details not found"
}

{
  "message": "Internal server error"
}

Response parameters (200)

Field	Type	Description
`vin`	string	Example: `1HGCM82633A004352`.
`stockNumber`	string	Example: `STK-4471`.
`registrationNumber`	string	Example: `KA01AB1234`.
`dealerVinID`	string	Spyne's record identifier, returned by the processing request. Example: `3bd1c257-9b32-4933-8cf4-a445fd5b37b8`.
`source`	string	Example: `API`.
`dealerId`	string	Team the record is attributed to. Example: `86fc402add`.
`clientMetaData`	object	Opaque metadata echoed back exactly as supplied on the processing request.
`mediaData`	object
`mediaData.image`	object	Catalog image output. Present when catalog processing was requested.
`mediaData.image.skuId`	string	Example: `sku_9f2c`.
`mediaData.image.aiStatus`	string	Example: `YET_TO_START`.
`mediaData.image.qcStatus`	string	Example: `PENDING`.
`mediaData.image.imageData`	object[]
`mediaData.image.imageData[].angle`	string	Example: `front`.
`mediaData.image.imageData[].status`	string	Example: `Yet to Start`.
`mediaData.image.imageData[].frameNo`	integer	Example: `1`.
`mediaData.image.imageData[].imageId`	string	Example: `img-bbef1ea1-e055-4571-aa16-02965d1fef14`.
`mediaData.image.imageData[].imageName`	string	Example: `0c4fb0ff-0323-4957-a53c-ffed1d385df4`.
`mediaData.image.imageData[].inputImage`	string	Example: `https://cdn.example.com/veh/front.jpg`.
`mediaData.image.imageData[].outputImage`	string	Example: `https://cdn.example.com/veh/front-processed.jpg`.
`mediaData.image.imageData[].backgroundId`	string	Example: `13488`.
`mediaData.image.imageData[].category`	string	Example: `Exterior`.
`mediaData.image.imageData[].clientMetaData`	object	Opaque per-image metadata echoed back exactly as supplied on the processing request.
`mediaData.spin`	object	360 spin output. Present when spin processing was requested.
`mediaData.spin.skuId`	string	Example: `sku_7a11`.
`mediaData.spin.aiStatus`	string	Example: `COMPLETED`.
`mediaData.spin.qcStatus`	string	Example: `APPROVED`.
`mediaData.spin.spinIframe`	string	Example: `https://spin.spyne.ai/embed/abc123`.
`mediaData.spin.spinUrl`	string	Example: `https://spin.spyne.ai/input/abc123`.
`mediaData.spin.thumbnailUrl`	string	Example: `https://cdn.example.com/spin-thumb.jpg`.
`mediaData.spin.inputVideoUrl`	string	Example: `https://cdn.example.com/walkaround.mp4`.
`mediaData.video`	object	Feature video output. Present when feature video processing was requested.
`mediaData.video.aiStatus`	string	Example: `COMPLETED`.
`mediaData.video.qcStatus`	string	Example: `APPROVED`.
`mediaData.video.videoId`	string	Example: `vid_5512`.
`mediaData.video.videoUrl`	string	Example: `https://cdn.example.com/feature.mp4`.
`mediaData.video.iframeUrl`	string	Example: `https://video.spyne.ai/embed/vid_5512`.
`mediaData.video.processingStatus`	string	Example: `DONE`.
`inputData`	object	Echo of the source assets, when recorded against the vehicle.
`inputData.assetsInfo`	object

Errors

Status	Meaning	When it happens
`400`	Bad Request	No identifier supplied, missing auth context, or a bad request relayed from the inventory service.
`401`	Unauthorized	Missing or invalid credential.
`404`	Not Found	No vehicle matches the supplied identifier.
`500`	Internal Server Error	Unexpected error, or the inventory service was unreachable.

Status values

Field	Values	Meaning
`aiStatus`	`DONE` · `PROCESSING` · `FAILED`	AI processing lifecycle
`qcStatus`	`qc_done` · `pending` · `rejected`	Manual quality check

📘
Show media only when aiStatus is DONE and qcStatus is qc_done. Only the media types you requested appear in mediaData. Surface rejectReason to your users when QC rejects an asset.

Prefer push over polling? Set up a webhook: it delivers the same payload. Field-by-field detail: Explaining API and Webhook Response.