Skip to main content

💥 API versions

Currently we maintain the following versions of our public API:

Compatibility​

Inside one API version we introduce only backward compatible changes.

The following changes are considered backwards compatible:

  • addition of new HTTP resources
  • support for additional method on existing HTTP resources
  • new optional attributes in a payload
  • previously required attributes in a payload being made optional
  • new attributes or elements introduced in an output

The following changes are considered backwards incompatible:

  • removal of a previously supported HTTP resource
  • an HTTP resource no longer responding to a previously supported HTTP method
  • a new required attribute in a payload
  • previously optional payload attribute now being required
  • a previously always present attribute an output that is now either optional or not present

v1 → v2 changes​

Overview​

Terminology changes​

  • Product → Catalog Item
    /v1/products → /v2/catalog-items
  • Detection job → Image Recognition Task
    /v1/detection-jobs → /v2/image-recognition/tasks
  • Detection job prediction → Image Recognition Result
    /v1/detection-jobs/{detection_job_uuid}/predictions/{detection_job_prediction_uuid} → /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid}

Response on the image recognition result​

More consistent and informative response for Image Recognition Results

Old responseNew response
{
  "detections": {...},
  "planogram": [...],
  "postprocessingResults": {
    "realogram": [...],
    "shares": [...]
  }
}
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_uuid": "5642ad1c-6ada-4d18-86e6-3cce085fba4b",
  "image_url": "https://example.com/",
  "duration": 3.5,
  "created_at": "2024-01-01T12:00:00.000Z",
  "updated_at": "2024-01-01T12:00:00.000Z",
  "postprocessing_results": {
    "realogram": [...],
    "shares": [...]
  },
  "coco": {...},
  "confidence_score": 0.98
}

Timeouts​

On sync image recognition endpoint (/v2/image-recognition/{task_uuid}/sync-image), if the image processing takes longer than the timeout, the endpoint will return empty result and a 408 status code. However, the processing will continue running in the background.

To get an update on its status, use the /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid} endpoint with provided result UUID.

Field naming​

Switched from "camelCase" naming to "snake_case":
customId → custom_id

Pagination​

Changed cursor pagination to limit/offset pagination:
/v1/...?limit=X&cursor=Y → /v2/...?limit=X&offset=Y

Also renamed collection array in the response to items.

Detailed changes​

/v1/detection-jobs → /v2/image-recognition/tasks​

  • Pagination:
    • Added limit query parameter
    • Added offset query parameter
  • Changed response from array [...] to an object { "items": [...], "total": 0, "limit": 0, "offset": 0 }
  • Fields removed:
    • userId
    • planogramImageUrl
    • planogramAnnotations
    • planogramMatchPercentageThreshold
  • Field added user_uuid
  • Fields renamed:
    • createdAt → created_at
    • updatedAt → updated_at
    • computeRealogram → compute_realogram
    • computeShares → compute_shares
    • products → catalog_items

/v1/detection-jobs/{detection_job_uuid} → /v2/image-recognition/{task_uuid}​

See above.

/v1/detection-jobs/{detection_job_uuid}/image → /v2/image-recognition/{task_uuid}/sync-image​

Same response as in /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid}

/v1/detection-jobs/{detection_job_uuid}/urls → /v2/image-recognition/{task_uuid}/urls​

No changes.

/v1/detection-jobs/{detection_job_uuid}/predictions → /v2/image-recognition/{task_uuid}/results​

  • Changed pagination from cursor to limit/offset:
    • Added offset query parameter
    • Removed cursor query parameter
    • Renamed field predictions to items
  • Renamed query parameters:
    • startDateTime → start_datetime
    • endDateTime → end_datetime
  • Renamed fields:
    • imageUrl → image_url
    • postprocessingResults → postprocessing_results
    • processingDuration → duration
    • createdAt → created_at
    • updatedAt → updated_at
  • Added field task_uuid
  • Renamed field prediction to coco, also changed field to contain object with coco formatted result instead of serialized string

/v1/detection-jobs/{detection_job_uuid}/predictions/{detection_job_prediction_uuid} → /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid}​

See above.

/v1/products → /v2/catalog-items​

  • Changed pagination from cursor to limit/offset:
    • Added offset query parameter
    • Removed cursor query parameter
    • Renamed field products to items
  • Removed field id
  • Renamed fields:
    • thumbnailUrl → thumbnail_url
    • customId → custom_id
    • containerType → container_type
    • createdAt → created_at
    • updatedAt → updated_at
  • Added query parameters to filter items by exact match:
    • name
    • custom_id
    • barcode

/v1/products/{product_uuid}/upload-reference-images → /v2/catalog-items/{item_uuid}/reference-images​

See above.

/v1/products/{product_uuid}/asset-requests/one-faced-asset → /v2/catalog-items/{item_uuid}/asset-requests/one-faced-asset​

No changes.